[1] | 1 | /** @file
|
---|
| 2 | *
|
---|
| 3 | * VirtualBox COM base classes definition
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[8155] | 7 | * Copyright (C) 2006-2007 Sun Microsystems, Inc.
|
---|
[1] | 8 | *
|
---|
| 9 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 10 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 11 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
[5999] | 12 | * General Public License (GPL) as published by the Free Software
|
---|
| 13 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 14 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 15 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
[8155] | 16 | *
|
---|
| 17 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
| 18 | * Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
| 19 | * additional information or have any questions.
|
---|
[1] | 20 | */
|
---|
| 21 |
|
---|
| 22 | #ifndef ____H_VIRTUALBOXBASEIMPL
|
---|
| 23 | #define ____H_VIRTUALBOXBASEIMPL
|
---|
| 24 |
|
---|
[16560] | 25 | #include <iprt/cdefs.h>
|
---|
| 26 | #include <iprt/critsect.h>
|
---|
| 27 | #include <iprt/thread.h>
|
---|
| 28 |
|
---|
| 29 | #include <list>
|
---|
| 30 | #include <map>
|
---|
| 31 |
|
---|
[1] | 32 | #include "VBox/com/ErrorInfo.h"
|
---|
| 33 |
|
---|
| 34 | #include "VBox/com/VirtualBox.h"
|
---|
| 35 |
|
---|
[16560] | 36 | // avoid including VBox/settings.h and VBox/xml.h;
|
---|
| 37 | // only declare the classes
|
---|
| 38 | namespace settings
|
---|
| 39 | {
|
---|
| 40 | class XmlTreeBackend;
|
---|
| 41 | class TreeBackend;
|
---|
| 42 | class Key;
|
---|
| 43 | }
|
---|
[6076] | 44 |
|
---|
[16560] | 45 | namespace xml
|
---|
| 46 | {
|
---|
| 47 | class File;
|
---|
| 48 | }
|
---|
| 49 |
|
---|
[1] | 50 | #include "AutoLock.h"
|
---|
| 51 |
|
---|
| 52 | using namespace com;
|
---|
[7992] | 53 | using namespace util;
|
---|
[1] | 54 |
|
---|
[6935] | 55 | #if !defined (VBOX_WITH_XPCOM)
|
---|
[1] | 56 |
|
---|
| 57 | #include <atlcom.h>
|
---|
| 58 |
|
---|
[13580] | 59 | /* use a special version of the singleton class factory,
|
---|
| 60 | * see KB811591 in msdn for more info. */
|
---|
[1] | 61 |
|
---|
| 62 | #undef DECLARE_CLASSFACTORY_SINGLETON
|
---|
| 63 | #define DECLARE_CLASSFACTORY_SINGLETON(obj) DECLARE_CLASSFACTORY_EX(CMyComClassFactorySingleton<obj>)
|
---|
| 64 |
|
---|
| 65 | template <class T>
|
---|
| 66 | class CMyComClassFactorySingleton : public CComClassFactory
|
---|
| 67 | {
|
---|
| 68 | public:
|
---|
[14944] | 69 | CMyComClassFactorySingleton() : m_hrCreate(S_OK){}
|
---|
| 70 | virtual ~CMyComClassFactorySingleton(){}
|
---|
| 71 | // IClassFactory
|
---|
| 72 | STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid, void** ppvObj)
|
---|
| 73 | {
|
---|
| 74 | HRESULT hRes = E_POINTER;
|
---|
| 75 | if (ppvObj != NULL)
|
---|
| 76 | {
|
---|
| 77 | *ppvObj = NULL;
|
---|
| 78 | // Aggregation is not supported in singleton objects.
|
---|
| 79 | ATLASSERT(pUnkOuter == NULL);
|
---|
| 80 | if (pUnkOuter != NULL)
|
---|
| 81 | hRes = CLASS_E_NOAGGREGATION;
|
---|
| 82 | else
|
---|
| 83 | {
|
---|
| 84 | if (m_hrCreate == S_OK && m_spObj == NULL)
|
---|
| 85 | {
|
---|
| 86 | Lock();
|
---|
| 87 | __try
|
---|
| 88 | {
|
---|
| 89 | // Fix: The following If statement was moved inside the __try statement.
|
---|
| 90 | // Did another thread arrive here first?
|
---|
| 91 | if (m_hrCreate == S_OK && m_spObj == NULL)
|
---|
| 92 | {
|
---|
| 93 | // lock the module to indicate activity
|
---|
| 94 | // (necessary for the monitor shutdown thread to correctly
|
---|
| 95 | // terminate the module in case when CreateInstance() fails)
|
---|
| 96 | _pAtlModule->Lock();
|
---|
| 97 | CComObjectCached<T> *p;
|
---|
| 98 | m_hrCreate = CComObjectCached<T>::CreateInstance(&p);
|
---|
| 99 | if (SUCCEEDED(m_hrCreate))
|
---|
| 100 | {
|
---|
| 101 | m_hrCreate = p->QueryInterface(IID_IUnknown, (void**)&m_spObj);
|
---|
| 102 | if (FAILED(m_hrCreate))
|
---|
| 103 | {
|
---|
| 104 | delete p;
|
---|
| 105 | }
|
---|
| 106 | }
|
---|
| 107 | _pAtlModule->Unlock();
|
---|
| 108 | }
|
---|
| 109 | }
|
---|
| 110 | __finally
|
---|
| 111 | {
|
---|
| 112 | Unlock();
|
---|
| 113 | }
|
---|
| 114 | }
|
---|
| 115 | if (m_hrCreate == S_OK)
|
---|
| 116 | {
|
---|
| 117 | hRes = m_spObj->QueryInterface(riid, ppvObj);
|
---|
| 118 | }
|
---|
| 119 | else
|
---|
| 120 | {
|
---|
| 121 | hRes = m_hrCreate;
|
---|
| 122 | }
|
---|
| 123 | }
|
---|
| 124 | }
|
---|
| 125 | return hRes;
|
---|
| 126 | }
|
---|
| 127 | HRESULT m_hrCreate;
|
---|
| 128 | CComPtr<IUnknown> m_spObj;
|
---|
[1] | 129 | };
|
---|
| 130 |
|
---|
[13580] | 131 | #endif /* !defined (VBOX_WITH_XPCOM) */
|
---|
[1] | 132 |
|
---|
| 133 | // macros
|
---|
| 134 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 135 |
|
---|
| 136 | /**
|
---|
[6076] | 137 | * Special version of the Assert macro to be used within VirtualBoxBase
|
---|
[1] | 138 | * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 139 | *
|
---|
| 140 | * In the debug build, this macro is equivalent to Assert.
|
---|
| 141 | * In the release build, this macro uses |setError (E_FAIL, ...)| to set the
|
---|
| 142 | * error info from the asserted expression.
|
---|
| 143 | *
|
---|
| 144 | * @see VirtualBoxSupportErrorInfoImpl::setError
|
---|
| 145 | *
|
---|
| 146 | * @param expr Expression which should be true.
|
---|
| 147 | */
|
---|
| 148 | #if defined (DEBUG)
|
---|
| 149 | #define ComAssert(expr) Assert (expr)
|
---|
| 150 | #else
|
---|
| 151 | #define ComAssert(expr) \
|
---|
| 152 | do { \
|
---|
| 153 | if (!(expr)) \
|
---|
| 154 | setError (E_FAIL, "Assertion failed: [%s] at '%s' (%d) in %s.\n" \
|
---|
| 155 | "Please contact the product vendor!", \
|
---|
| 156 | #expr, __FILE__, __LINE__, __PRETTY_FUNCTION__); \
|
---|
| 157 | } while (0)
|
---|
| 158 | #endif
|
---|
| 159 |
|
---|
| 160 | /**
|
---|
[6076] | 161 | * Special version of the AssertMsg macro to be used within VirtualBoxBase
|
---|
[1] | 162 | * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 163 | *
|
---|
| 164 | * See ComAssert for more info.
|
---|
| 165 | *
|
---|
| 166 | * @param expr Expression which should be true.
|
---|
| 167 | * @param a printf argument list (in parenthesis).
|
---|
| 168 | */
|
---|
| 169 | #if defined (DEBUG)
|
---|
| 170 | #define ComAssertMsg(expr, a) AssertMsg (expr, a)
|
---|
| 171 | #else
|
---|
| 172 | #define ComAssertMsg(expr, a) \
|
---|
| 173 | do { \
|
---|
| 174 | if (!(expr)) \
|
---|
| 175 | setError (E_FAIL, "Assertion failed: [%s] at '%s' (%d) in %s.\n" \
|
---|
| 176 | "%s.\n" \
|
---|
| 177 | "Please contact the product vendor!", \
|
---|
| 178 | #expr, __FILE__, __LINE__, __PRETTY_FUNCTION__, Utf8StrFmt a .raw()); \
|
---|
| 179 | } while (0)
|
---|
| 180 | #endif
|
---|
| 181 |
|
---|
| 182 | /**
|
---|
[6076] | 183 | * Special version of the AssertRC macro to be used within VirtualBoxBase
|
---|
[1] | 184 | * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 185 | *
|
---|
| 186 | * See ComAssert for more info.
|
---|
| 187 | *
|
---|
| 188 | * @param vrc VBox status code.
|
---|
| 189 | */
|
---|
| 190 | #if defined (DEBUG)
|
---|
| 191 | #define ComAssertRC(vrc) AssertRC (vrc)
|
---|
| 192 | #else
|
---|
[13837] | 193 | #define ComAssertRC(vrc) ComAssertMsgRC (vrc, ("%Rra", vrc))
|
---|
[1] | 194 | #endif
|
---|
| 195 |
|
---|
| 196 | /**
|
---|
[6076] | 197 | * Special version of the AssertMsgRC macro to be used within VirtualBoxBase
|
---|
[1] | 198 | * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 199 | *
|
---|
| 200 | * See ComAssert for more info.
|
---|
| 201 | *
|
---|
| 202 | * @param vrc VBox status code.
|
---|
| 203 | * @param msg printf argument list (in parenthesis).
|
---|
| 204 | */
|
---|
| 205 | #if defined (DEBUG)
|
---|
| 206 | #define ComAssertMsgRC(vrc, msg) AssertMsgRC (vrc, msg)
|
---|
| 207 | #else
|
---|
[13835] | 208 | #define ComAssertMsgRC(vrc, msg) ComAssertMsg (RT_SUCCESS (vrc), msg)
|
---|
[1] | 209 | #endif
|
---|
| 210 |
|
---|
| 211 |
|
---|
| 212 | /**
|
---|
[6076] | 213 | * Special version of the AssertFailed macro to be used within VirtualBoxBase
|
---|
[1] | 214 | * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 215 | *
|
---|
| 216 | * See ComAssert for more info.
|
---|
| 217 | */
|
---|
| 218 | #if defined (DEBUG)
|
---|
| 219 | #define ComAssertFailed() AssertFailed()
|
---|
| 220 | #else
|
---|
| 221 | #define ComAssertFailed() \
|
---|
| 222 | do { \
|
---|
| 223 | setError (E_FAIL, "Assertion failed at '%s' (%d) in %s.\n" \
|
---|
| 224 | "Please contact the product vendor!", \
|
---|
| 225 | __FILE__, __LINE__, __PRETTY_FUNCTION__); \
|
---|
| 226 | } while (0)
|
---|
| 227 | #endif
|
---|
| 228 |
|
---|
| 229 | /**
|
---|
[6076] | 230 | * Special version of the AssertMsgFailed macro to be used within VirtualBoxBase
|
---|
[1] | 231 | * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 232 | *
|
---|
| 233 | * See ComAssert for more info.
|
---|
| 234 | *
|
---|
| 235 | * @param a printf argument list (in parenthesis).
|
---|
| 236 | */
|
---|
| 237 | #if defined (DEBUG)
|
---|
| 238 | #define ComAssertMsgFailed(a) AssertMsgFailed(a)
|
---|
| 239 | #else
|
---|
| 240 | #define ComAssertMsgFailed(a) \
|
---|
| 241 | do { \
|
---|
| 242 | setError (E_FAIL, "Assertion failed at '%s' (%d) in %s.\n" \
|
---|
| 243 | "%s.\n" \
|
---|
| 244 | "Please contact the product vendor!", \
|
---|
| 245 | __FILE__, __LINE__, __PRETTY_FUNCTION__, Utf8StrFmt a .raw()); \
|
---|
| 246 | } while (0)
|
---|
| 247 | #endif
|
---|
| 248 |
|
---|
| 249 | /**
|
---|
[6076] | 250 | * Special version of the ComAssertMsgFailed macro that additionally takes
|
---|
| 251 | * line number, file and function arguments to inject an assertion position
|
---|
| 252 | * that differs from the position where this macro is instantiated.
|
---|
| 253 | *
|
---|
| 254 | * @param a printf argument list (in parenthesis).
|
---|
| 255 | * @param file, line, func Line number (int), file and function (const char *).
|
---|
| 256 | */
|
---|
| 257 | #if defined (DEBUG)
|
---|
| 258 | #define ComAssertMsgFailedPos(a, file, line, func) \
|
---|
| 259 | do { \
|
---|
| 260 | AssertMsg1 ((const char *) 0, line, file, func); \
|
---|
| 261 | AssertMsg2 a; \
|
---|
| 262 | AssertBreakpoint(); \
|
---|
| 263 | } while (0)
|
---|
| 264 | #else
|
---|
| 265 | #define ComAssertMsgFailedPos(a, file, line, func) \
|
---|
| 266 | do { \
|
---|
| 267 | setError (E_FAIL, \
|
---|
| 268 | "Assertion failed at '%s' (%d) in %s.\n" \
|
---|
| 269 | "%s.\n" \
|
---|
| 270 | "Please contact the product vendor!", \
|
---|
| 271 | file, line, func, Utf8StrFmt a .raw()); \
|
---|
| 272 | } while (0)
|
---|
| 273 | #endif
|
---|
| 274 |
|
---|
| 275 | /**
|
---|
| 276 | * Special version of the AssertComRC macro to be used within VirtualBoxBase
|
---|
[1] | 277 | * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 278 | *
|
---|
| 279 | * See ComAssert for more info.
|
---|
| 280 | *
|
---|
| 281 | * @param rc COM result code
|
---|
| 282 | */
|
---|
| 283 | #if defined (DEBUG)
|
---|
| 284 | #define ComAssertComRC(rc) AssertComRC (rc)
|
---|
| 285 | #else
|
---|
[14959] | 286 | #define ComAssertComRC(rc) ComAssertMsg (SUCCEEDED (rc), ("COM RC = %Rhrc (0x%08X)", (rc), (rc)))
|
---|
[1] | 287 | #endif
|
---|
| 288 |
|
---|
| 289 |
|
---|
| 290 | /** Special version of ComAssert that returns ret if expr fails */
|
---|
| 291 | #define ComAssertRet(expr, ret) \
|
---|
| 292 | do { ComAssert (expr); if (!(expr)) return (ret); } while (0)
|
---|
| 293 | /** Special version of ComAssertMsg that returns ret if expr fails */
|
---|
| 294 | #define ComAssertMsgRet(expr, a, ret) \
|
---|
| 295 | do { ComAssertMsg (expr, a); if (!(expr)) return (ret); } while (0)
|
---|
| 296 | /** Special version of ComAssertRC that returns ret if vrc does not succeed */
|
---|
| 297 | #define ComAssertRCRet(vrc, ret) \
|
---|
[13835] | 298 | do { ComAssertRC (vrc); if (!RT_SUCCESS (vrc)) return (ret); } while (0)
|
---|
[1] | 299 | /** Special version of ComAssertMsgRC that returns ret if vrc does not succeed */
|
---|
| 300 | #define ComAssertMsgRCRet(vrc, msg, ret) \
|
---|
[13835] | 301 | do { ComAssertMsgRC (vrc, msg); if (!RT_SUCCESS (vrc)) return (ret); } while (0)
|
---|
[1] | 302 | /** Special version of ComAssertFailed that returns ret */
|
---|
| 303 | #define ComAssertFailedRet(ret) \
|
---|
| 304 | do { ComAssertFailed(); return (ret); } while (0)
|
---|
| 305 | /** Special version of ComAssertMsgFailed that returns ret */
|
---|
| 306 | #define ComAssertMsgFailedRet(msg, ret) \
|
---|
| 307 | do { ComAssertMsgFailed (msg); return (ret); } while (0)
|
---|
| 308 | /** Special version of ComAssertComRC that returns ret if rc does not succeed */
|
---|
| 309 | #define ComAssertComRCRet(rc, ret) \
|
---|
| 310 | do { ComAssertComRC (rc); if (!SUCCEEDED (rc)) return (ret); } while (0)
|
---|
| 311 | /** Special version of ComAssertComRC that returns rc if rc does not succeed */
|
---|
| 312 | #define ComAssertComRCRetRC(rc) \
|
---|
| 313 | do { ComAssertComRC (rc); if (!SUCCEEDED (rc)) return (rc); } while (0)
|
---|
| 314 |
|
---|
| 315 |
|
---|
[14624] | 316 | /** Special version of ComAssert that evaluates eval and breaks if expr fails */
|
---|
[1] | 317 | #define ComAssertBreak(expr, eval) \
|
---|
| 318 | if (1) { ComAssert (expr); if (!(expr)) { eval; break; } } else do {} while (0)
|
---|
[14624] | 319 | /** Special version of ComAssertMsg that evaluates eval and breaks if expr fails */
|
---|
[1] | 320 | #define ComAssertMsgBreak(expr, a, eval) \
|
---|
| 321 | if (1) { ComAssertMsg (expr, a); if (!(expr)) { eval; break; } } else do {} while (0)
|
---|
[14624] | 322 | /** Special version of ComAssertRC that evaluates eval and breaks if vrc does not succeed */
|
---|
[1] | 323 | #define ComAssertRCBreak(vrc, eval) \
|
---|
[13835] | 324 | if (1) { ComAssertRC (vrc); if (!RT_SUCCESS (vrc)) { eval; break; } } else do {} while (0)
|
---|
[14624] | 325 | /** Special version of ComAssertMsgRC that evaluates eval and breaks if vrc does not succeed */
|
---|
[1] | 326 | #define ComAssertMsgRCBreak(vrc, msg, eval) \
|
---|
[13835] | 327 | if (1) { ComAssertMsgRC (vrc, msg); if (!RT_SUCCESS (vrc)) { eval; break; } } else do {} while (0)
|
---|
[14624] | 328 | /** Special version of ComAssertFailed that evaluates eval and breaks */
|
---|
[1] | 329 | #define ComAssertFailedBreak(eval) \
|
---|
| 330 | if (1) { ComAssertFailed(); { eval; break; } } else do {} while (0)
|
---|
[14624] | 331 | /** Special version of ComAssertMsgFailed that evaluates eval and breaks */
|
---|
[1] | 332 | #define ComAssertMsgFailedBreak(msg, eval) \
|
---|
| 333 | if (1) { ComAssertMsgFailed (msg); { eval; break; } } else do {} while (0)
|
---|
[14624] | 334 | /** Special version of ComAssertComRC that evaluates eval and breaks if rc does not succeed */
|
---|
[1] | 335 | #define ComAssertComRCBreak(rc, eval) \
|
---|
| 336 | if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { eval; break; } } else do {} while (0)
|
---|
| 337 | /** Special version of ComAssertComRC that just breaks if rc does not succeed */
|
---|
| 338 | #define ComAssertComRCBreakRC(rc) \
|
---|
| 339 | if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { break; } } else do {} while (0)
|
---|
| 340 |
|
---|
[6076] | 341 |
|
---|
[14624] | 342 | /** Special version of ComAssert that evaluates eval and throws it if expr fails */
|
---|
[6076] | 343 | #define ComAssertThrow(expr, eval) \
|
---|
| 344 | if (1) { ComAssert (expr); if (!(expr)) { throw (eval); } } else do {} while (0)
|
---|
[14624] | 345 | /** Special version of ComAssertMsg that evaluates eval and throws it if expr fails */
|
---|
[6076] | 346 | #define ComAssertMsgThrow(expr, a, eval) \
|
---|
| 347 | if (1) { ComAssertMsg (expr, a); if (!(expr)) { throw (eval); } } else do {} while (0)
|
---|
[14624] | 348 | /** Special version of ComAssertRC that evaluates eval and throws it if vrc does not succeed */
|
---|
[6076] | 349 | #define ComAssertRCThrow(vrc, eval) \
|
---|
[13835] | 350 | if (1) { ComAssertRC (vrc); if (!RT_SUCCESS (vrc)) { throw (eval); } } else do {} while (0)
|
---|
[14624] | 351 | /** Special version of ComAssertMsgRC that evaluates eval and throws it if vrc does not succeed */
|
---|
[6076] | 352 | #define ComAssertMsgRCThrow(vrc, msg, eval) \
|
---|
[13835] | 353 | if (1) { ComAssertMsgRC (vrc, msg); if (!RT_SUCCESS (vrc)) { throw (eval); } } else do {} while (0)
|
---|
[14624] | 354 | /** Special version of ComAssertFailed that evaluates eval and throws it */
|
---|
[6076] | 355 | #define ComAssertFailedThrow(eval) \
|
---|
| 356 | if (1) { ComAssertFailed(); { throw (eval); } } else do {} while (0)
|
---|
[14624] | 357 | /** Special version of ComAssertMsgFailed that evaluates eval and throws it */
|
---|
[6076] | 358 | #define ComAssertMsgFailedThrow(msg, eval) \
|
---|
| 359 | if (1) { ComAssertMsgFailed (msg); { throw (eval); } } else do {} while (0)
|
---|
[14624] | 360 | /** Special version of ComAssertComRC that evaluates eval and throws it if rc does not succeed */
|
---|
[6076] | 361 | #define ComAssertComRCThrow(rc, eval) \
|
---|
| 362 | if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { throw (eval); } } else do {} while (0)
|
---|
| 363 | /** Special version of ComAssertComRC that just throws rc if rc does not succeed */
|
---|
| 364 | #define ComAssertComRCThrowRC(rc) \
|
---|
| 365 | if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { throw rc; } } else do {} while (0)
|
---|
| 366 |
|
---|
[14588] | 367 | ////////////////////////////////////////////////////////////////////////////////
|
---|
[6076] | 368 |
|
---|
[14588] | 369 | /**
|
---|
| 370 | * Checks that the pointer argument is not NULL and returns E_INVALIDARG +
|
---|
| 371 | * extended error info on failure.
|
---|
[14624] | 372 | * @param arg Input pointer-type argument (strings, interface pointers...)
|
---|
[14588] | 373 | */
|
---|
| 374 | #define CheckComArgNotNull(arg) \
|
---|
| 375 | do { \
|
---|
| 376 | if ((arg) == NULL) \
|
---|
| 377 | return setError (E_INVALIDARG, tr ("Argument %s is NULL"), #arg); \
|
---|
| 378 | } while (0)
|
---|
| 379 |
|
---|
| 380 | /**
|
---|
| 381 | * Checks that safe array argument is not NULL and returns E_INVALIDARG +
|
---|
| 382 | * extended error info on failure.
|
---|
[14624] | 383 | * @param arg Input safe array argument (strings, interface pointers...)
|
---|
[14588] | 384 | */
|
---|
| 385 | #define CheckComArgSafeArrayNotNull(arg) \
|
---|
| 386 | do { \
|
---|
| 387 | if (ComSafeArrayInIsNull (arg)) \
|
---|
| 388 | return setError (E_INVALIDARG, tr ("Argument %s is NULL"), #arg); \
|
---|
| 389 | } while (0)
|
---|
| 390 |
|
---|
| 391 | /**
|
---|
| 392 | * Checks that the string argument is not a NULL or empty string and returns
|
---|
| 393 | * E_INVALIDARG + extended error info on failure.
|
---|
| 394 | * @param arg Input string argument (BSTR etc.).
|
---|
| 395 | */
|
---|
| 396 | #define CheckComArgStrNotEmptyOrNull(arg) \
|
---|
| 397 | do { \
|
---|
| 398 | if ((arg) == NULL || *(arg) == '\0') \
|
---|
| 399 | return setError (E_INVALIDARG, \
|
---|
| 400 | tr ("Argument %s is emtpy or NULL"), #arg); \
|
---|
| 401 | } while (0)
|
---|
| 402 |
|
---|
| 403 | /**
|
---|
| 404 | * Checks that the given expression (that must involve the argument) is true and
|
---|
| 405 | * returns E_INVALIDARG + extended error info on failure.
|
---|
| 406 | * @param arg Argument.
|
---|
| 407 | * @param expr Expression to evaluate.
|
---|
| 408 | */
|
---|
| 409 | #define CheckComArgExpr(arg, expr) \
|
---|
| 410 | do { \
|
---|
| 411 | if (!(expr)) \
|
---|
| 412 | return setError (E_INVALIDARG, \
|
---|
| 413 | tr ("Argument %s is invalid (must be %s)"), #arg, #expr); \
|
---|
| 414 | } while (0)
|
---|
| 415 |
|
---|
| 416 | /**
|
---|
| 417 | * Checks that the given expression (that must involve the argument) is true and
|
---|
| 418 | * returns E_INVALIDARG + extended error info on failure. The error message must
|
---|
| 419 | * be customized.
|
---|
| 420 | * @param arg Argument.
|
---|
| 421 | * @param expr Expression to evaluate.
|
---|
| 422 | * @param msg Parenthesized printf-like expression (must start with a verb,
|
---|
| 423 | * like "must be one of...", "is not within...").
|
---|
| 424 | */
|
---|
| 425 | #define CheckComArgExprMsg(arg, expr, msg) \
|
---|
| 426 | do { \
|
---|
| 427 | if (!(expr)) \
|
---|
| 428 | return setError (E_INVALIDARG, tr ("Argument %s %s"), \
|
---|
| 429 | #arg, Utf8StrFmt msg .raw()); \
|
---|
| 430 | } while (0)
|
---|
| 431 |
|
---|
| 432 | /**
|
---|
| 433 | * Checks that the given pointer to an output argument is valid and returns
|
---|
| 434 | * E_POINTER + extended error info otherwise.
|
---|
| 435 | * @param arg Pointer argument.
|
---|
| 436 | */
|
---|
| 437 | #define CheckComArgOutPointerValid(arg) \
|
---|
| 438 | do { \
|
---|
| 439 | if (!VALID_PTR (arg)) \
|
---|
| 440 | return setError (E_POINTER, \
|
---|
| 441 | tr ("Output argument %s points to invalid memory location (%p)"), \
|
---|
| 442 | #arg, (void *) (arg)); \
|
---|
| 443 | } while (0)
|
---|
| 444 |
|
---|
| 445 | /**
|
---|
| 446 | * Checks that the given pointer to an output safe array argument is valid and
|
---|
| 447 | * returns E_POINTER + extended error info otherwise.
|
---|
| 448 | * @param arg Safe array argument.
|
---|
| 449 | */
|
---|
| 450 | #define CheckComArgOutSafeArrayPointerValid(arg) \
|
---|
| 451 | do { \
|
---|
| 452 | if (ComSafeArrayOutIsNull (arg)) \
|
---|
| 453 | return setError (E_POINTER, \
|
---|
| 454 | tr ("Output argument %s points to invalid memory location (%p)"), \
|
---|
| 455 | #arg, (void *) (arg)); \
|
---|
| 456 | } while (0)
|
---|
| 457 |
|
---|
| 458 | /**
|
---|
[14624] | 459 | * Sets the extended error info and returns E_NOTIMPL.
|
---|
[14588] | 460 | */
|
---|
[14715] | 461 | #define ReturnComNotImplemented() \
|
---|
[14588] | 462 | do { \
|
---|
[14717] | 463 | return setError (E_NOTIMPL, tr ("Method %s is not implemented"), __FUNCTION__); \
|
---|
[14588] | 464 | } while (0)
|
---|
| 465 |
|
---|
| 466 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 467 |
|
---|
[1] | 468 | /// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
|
---|
| 469 | /**
|
---|
| 470 | * Checks whether this object is ready or not. Objects are typically ready
|
---|
| 471 | * after they are successfully created by their parent objects and become
|
---|
[14624] | 472 | * not ready when the respective parent itself becomes not ready or gets
|
---|
[1] | 473 | * destroyed while a reference to the child is still held by the caller
|
---|
| 474 | * (which prevents it from destruction).
|
---|
| 475 | *
|
---|
| 476 | * When this object is not ready, the macro sets error info and returns
|
---|
[14579] | 477 | * E_ACCESSDENIED (the translatable error message is defined in null context).
|
---|
[1] | 478 | * Otherwise, the macro does nothing.
|
---|
| 479 | *
|
---|
| 480 | * This macro <b>must</b> be used at the beginning of all interface methods
|
---|
| 481 | * (right after entering the class lock) in classes derived from both
|
---|
| 482 | * VirtualBoxBase and VirtualBoxSupportErrorInfoImpl.
|
---|
| 483 | */
|
---|
| 484 | #define CHECK_READY() \
|
---|
| 485 | do { \
|
---|
| 486 | if (!isReady()) \
|
---|
[14579] | 487 | return setError (E_ACCESSDENIED, tr ("The object is not ready")); \
|
---|
[1] | 488 | } while (0)
|
---|
| 489 |
|
---|
| 490 | /**
|
---|
[14624] | 491 | * Declares an empty constructor and destructor for the given class.
|
---|
[1] | 492 | * This is useful to prevent the compiler from generating the default
|
---|
| 493 | * ctor and dtor, which in turn allows to use forward class statements
|
---|
| 494 | * (instead of including their header files) when declaring data members of
|
---|
| 495 | * non-fundamental types with constructors (which are always called implicitly
|
---|
| 496 | * by constructors and by the destructor of the class).
|
---|
| 497 | *
|
---|
[14624] | 498 | * This macro is to be placed within (the public section of) the class
|
---|
[1] | 499 | * declaration. Its counterpart, DEFINE_EMPTY_CTOR_DTOR, must be placed
|
---|
| 500 | * somewhere in one of the translation units (usually .cpp source files).
|
---|
| 501 | *
|
---|
| 502 | * @param cls class to declare a ctor and dtor for
|
---|
| 503 | */
|
---|
| 504 | #define DECLARE_EMPTY_CTOR_DTOR(cls) cls(); ~cls();
|
---|
| 505 |
|
---|
| 506 | /**
|
---|
[14624] | 507 | * Defines an empty constructor and destructor for the given class.
|
---|
[1] | 508 | * See DECLARE_EMPTY_CTOR_DTOR for more info.
|
---|
| 509 | */
|
---|
| 510 | #define DEFINE_EMPTY_CTOR_DTOR(cls) \
|
---|
| 511 | cls::cls () {}; cls::~cls () {};
|
---|
| 512 |
|
---|
| 513 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 514 |
|
---|
| 515 | namespace stdx
|
---|
| 516 | {
|
---|
| 517 | /**
|
---|
| 518 | * A wrapper around the container that owns pointers it stores.
|
---|
| 519 | *
|
---|
| 520 | * @note
|
---|
| 521 | * Ownership is recognized only when destructing the container!
|
---|
| 522 | * Pointers are not deleted when erased using erase() etc.
|
---|
| 523 | *
|
---|
| 524 | * @param container
|
---|
| 525 | * class that meets Container requirements (for example, an instance of
|
---|
| 526 | * std::list<>, std::vector<> etc.). The given class must store
|
---|
| 527 | * pointers (for example, std::list <MyType *>).
|
---|
| 528 | */
|
---|
| 529 | template <typename container>
|
---|
| 530 | class ptr_container : public container
|
---|
| 531 | {
|
---|
| 532 | public:
|
---|
| 533 | ~ptr_container()
|
---|
| 534 | {
|
---|
| 535 | for (typename container::iterator it = container::begin();
|
---|
| 536 | it != container::end();
|
---|
| 537 | ++ it)
|
---|
| 538 | delete (*it);
|
---|
| 539 | }
|
---|
| 540 | };
|
---|
[5658] | 541 | }
|
---|
[1] | 542 |
|
---|
| 543 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 544 |
|
---|
[13580] | 545 | /**
|
---|
| 546 | * Abstract base class for all component classes implementing COM
|
---|
| 547 | * interfaces of the VirtualBox COM library.
|
---|
| 548 | *
|
---|
| 549 | * Declares functionality that should be available in all components.
|
---|
| 550 | *
|
---|
| 551 | * Note that this class is always subclassed using the virtual keyword so
|
---|
| 552 | * that only one instance of its VTBL and data is present in each derived class
|
---|
| 553 | * even in case if VirtualBoxBaseProto appears more than once among base classes
|
---|
| 554 | * of the particular component as a result of multiple inheritance.
|
---|
| 555 | *
|
---|
| 556 | * This makes it possible to have intermediate base classes used by several
|
---|
[14624] | 557 | * components that implement some common interface functionality but still let
|
---|
| 558 | * the final component classes choose what VirtualBoxBase variant it wants to
|
---|
[13580] | 559 | * use.
|
---|
| 560 | *
|
---|
| 561 | * Among the basic functionality implemented by this class is the primary object
|
---|
| 562 | * state that indicates if the object is ready to serve the calls, and if not,
|
---|
[14624] | 563 | * what stage it is currently at. Here is the primary state diagram:
|
---|
[13580] | 564 | *
|
---|
| 565 | * +-------------------------------------------------------+
|
---|
| 566 | * | |
|
---|
| 567 | * | (InitFailed) -----------------------+ |
|
---|
| 568 | * | ^ | |
|
---|
| 569 | * v | v |
|
---|
| 570 | * [*] ---> NotReady ----> (InInit) -----> Ready -----> (InUninit) ----+
|
---|
| 571 | * ^ | ^ | ^
|
---|
| 572 | * | v | v |
|
---|
| 573 | * | Limited | (MayUninit) --> (WillUninit)
|
---|
| 574 | * | | | |
|
---|
| 575 | * +-------+ +-------+
|
---|
| 576 | *
|
---|
| 577 | * The object is fully operational only when its state is Ready. The Limited
|
---|
| 578 | * state means that only some vital part of the object is operational, and it
|
---|
| 579 | * requires some sort of reinitialization to become fully operational. The
|
---|
| 580 | * NotReady state means the object is basically dead: it either was not yet
|
---|
| 581 | * initialized after creation at all, or was uninitialized and is waiting to be
|
---|
| 582 | * destroyed when the last reference to it is released. All other states are
|
---|
| 583 | * transitional.
|
---|
| 584 | *
|
---|
| 585 | * The NotReady->InInit->Ready, NotReady->InInit->Limited and
|
---|
| 586 | * NotReady->InInit->InitFailed transition is done by the AutoInitSpan smart
|
---|
| 587 | * class.
|
---|
| 588 | *
|
---|
| 589 | * The Limited->InInit->Ready, Limited->InInit->Limited and
|
---|
| 590 | * Limited->InInit->InitFailed transition is done by the AutoReinitSpan smart
|
---|
| 591 | * class.
|
---|
| 592 | *
|
---|
| 593 | * The Ready->InUninit->NotReady, InitFailed->InUninit->NotReady and
|
---|
| 594 | * WillUninit->InUninit->NotReady transitions are done by the AutoUninitSpan
|
---|
| 595 | * smart class.
|
---|
| 596 | *
|
---|
| 597 | * The Ready->MayUninit->Ready and Ready->MayUninit->WillUninit transitions are
|
---|
| 598 | * done by the AutoMayUninitSpan smart class.
|
---|
| 599 | *
|
---|
| 600 | * In order to maintain the primary state integrity and declared functionality
|
---|
| 601 | * all subclasses must:
|
---|
| 602 | *
|
---|
| 603 | * 1) Use the above Auto*Span classes to perform state transitions. See the
|
---|
[14624] | 604 | * individual class descriptions for details.
|
---|
[13580] | 605 | *
|
---|
| 606 | * 2) All public methods of subclasses (i.e. all methods that can be called
|
---|
| 607 | * directly, not only from within other methods of the subclass) must have a
|
---|
| 608 | * standard prolog as described in the AutoCaller and AutoLimitedCaller
|
---|
| 609 | * documentation. Alternatively, they must use addCaller()/releaseCaller()
|
---|
[14624] | 610 | * directly (and therefore have both the prolog and the epilog), but this is
|
---|
[13580] | 611 | * not recommended.
|
---|
| 612 | */
|
---|
| 613 | class ATL_NO_VTABLE VirtualBoxBaseProto : public Lockable
|
---|
[1] | 614 | {
|
---|
| 615 | public:
|
---|
| 616 |
|
---|
[13580] | 617 | enum State { NotReady, Ready, InInit, InUninit, InitFailed, Limited,
|
---|
| 618 | MayUninit, WillUninit };
|
---|
[1] | 619 |
|
---|
| 620 | protected:
|
---|
| 621 |
|
---|
[13580] | 622 | VirtualBoxBaseProto();
|
---|
| 623 | virtual ~VirtualBoxBaseProto();
|
---|
[1] | 624 |
|
---|
| 625 | public:
|
---|
| 626 |
|
---|
[8083] | 627 | // util::Lockable interface
|
---|
[7992] | 628 | virtual RWLockHandle *lockHandle() const;
|
---|
[1] | 629 |
|
---|
| 630 | /**
|
---|
[13580] | 631 | * Unintialization method.
|
---|
| 632 | *
|
---|
| 633 | * Must be called by all final implementations (component classes) when the
|
---|
| 634 | * last reference to the object is released, before calling the destructor.
|
---|
| 635 | *
|
---|
| 636 | * This method is also automatically called by the uninit() method of this
|
---|
| 637 | * object's parent if this object is a dependent child of a class derived
|
---|
| 638 | * from VirtualBoxBaseWithChildren (see
|
---|
| 639 | * VirtualBoxBaseWithChildren::addDependentChild).
|
---|
| 640 | *
|
---|
| 641 | * @note Never call this method the AutoCaller scope or after the
|
---|
| 642 | * #addCaller() call not paired by #releaseCaller() because it is a
|
---|
| 643 | * guaranteed deadlock. See AutoUninitSpan for details.
|
---|
[1] | 644 | */
|
---|
| 645 | virtual void uninit() {}
|
---|
| 646 |
|
---|
| 647 | virtual HRESULT addCaller (State *aState = NULL, bool aLimited = false);
|
---|
| 648 | virtual void releaseCaller();
|
---|
| 649 |
|
---|
| 650 | /**
|
---|
[13580] | 651 | * Adds a limited caller. This method is equivalent to doing
|
---|
| 652 | * <tt>addCaller (aState, true)</tt>, but it is preferred because provides
|
---|
| 653 | * better self-descriptiveness. See #addCaller() for more info.
|
---|
[1] | 654 | */
|
---|
| 655 | HRESULT addLimitedCaller (State *aState = NULL)
|
---|
| 656 | {
|
---|
| 657 | return addCaller (aState, true /* aLimited */);
|
---|
| 658 | }
|
---|
[6935] | 659 |
|
---|
[1] | 660 | /**
|
---|
[13580] | 661 | * Smart class that automatically increases the number of callers of the
|
---|
| 662 | * given VirtualBoxBase object when an instance is constructed and decreases
|
---|
| 663 | * it back when the created instance goes out of scope (i.e. gets destroyed).
|
---|
[1] | 664 | *
|
---|
[13580] | 665 | * If #rc() returns a failure after the instance creation, it means that
|
---|
| 666 | * the managed VirtualBoxBase object is not Ready, or in any other invalid
|
---|
| 667 | * state, so that the caller must not use the object and can return this
|
---|
| 668 | * failed result code to the upper level.
|
---|
[1] | 669 | *
|
---|
[13580] | 670 | * See VirtualBoxBase::addCaller(), VirtualBoxBase::addLimitedCaller() and
|
---|
| 671 | * VirtualBoxBase::releaseCaller() for more details about object callers.
|
---|
[1] | 672 | *
|
---|
[13580] | 673 | * @param aLimited |false| if this template should use
|
---|
[1] | 674 | * VirtualiBoxBase::addCaller() calls to add callers, or
|
---|
| 675 | * |true| if VirtualiBoxBase::addLimitedCaller() should be
|
---|
| 676 | * used.
|
---|
| 677 | *
|
---|
[14624] | 678 | * @note It is preferable to use the AutoCaller and AutoLimitedCaller
|
---|
[13580] | 679 | * classes than specify the @a aLimited argument, for better
|
---|
| 680 | * self-descriptiveness.
|
---|
[1] | 681 | */
|
---|
| 682 | template <bool aLimited>
|
---|
| 683 | class AutoCallerBase
|
---|
| 684 | {
|
---|
| 685 | public:
|
---|
| 686 |
|
---|
| 687 | /**
|
---|
[13580] | 688 | * Increases the number of callers of the given object by calling
|
---|
| 689 | * VirtualBoxBase::addCaller().
|
---|
[3033] | 690 | *
|
---|
[13580] | 691 | * @param aObj Object to add a caller to. If NULL, this
|
---|
[3033] | 692 | * instance is effectively turned to no-op (where
|
---|
| 693 | * rc() will return S_OK and state() will be
|
---|
| 694 | * NotReady).
|
---|
[1] | 695 | */
|
---|
[13580] | 696 | AutoCallerBase (VirtualBoxBaseProto *aObj)
|
---|
[3033] | 697 | : mObj (aObj)
|
---|
| 698 | , mRC (S_OK)
|
---|
| 699 | , mState (NotReady)
|
---|
[1] | 700 | {
|
---|
[3033] | 701 | if (mObj)
|
---|
| 702 | mRC = mObj->addCaller (&mState, aLimited);
|
---|
[1] | 703 | }
|
---|
| 704 |
|
---|
| 705 | /**
|
---|
[13580] | 706 | * If the number of callers was successfully increased, decreases it
|
---|
| 707 | * using VirtualBoxBase::releaseCaller(), otherwise does nothing.
|
---|
[1] | 708 | */
|
---|
| 709 | ~AutoCallerBase()
|
---|
| 710 | {
|
---|
[3033] | 711 | if (mObj && SUCCEEDED (mRC))
|
---|
[1] | 712 | mObj->releaseCaller();
|
---|
| 713 | }
|
---|
| 714 |
|
---|
| 715 | /**
|
---|
[13580] | 716 | * Stores the result code returned by VirtualBoxBase::addCaller() after
|
---|
| 717 | * instance creation or after the last #add() call. A successful result
|
---|
| 718 | * code means the number of callers was successfully increased.
|
---|
[1] | 719 | */
|
---|
| 720 | HRESULT rc() const { return mRC; }
|
---|
| 721 |
|
---|
| 722 | /**
|
---|
[13580] | 723 | * Returns |true| if |SUCCEEDED (rc())| is |true|, for convenience.
|
---|
| 724 | * |true| means the number of callers was successfully increased.
|
---|
[1] | 725 | */
|
---|
| 726 | bool isOk() const { return SUCCEEDED (mRC); }
|
---|
| 727 |
|
---|
| 728 | /**
|
---|
[13580] | 729 | * Stores the object state returned by VirtualBoxBase::addCaller() after
|
---|
| 730 | * instance creation or after the last #add() call.
|
---|
[1] | 731 | */
|
---|
| 732 | State state() const { return mState; }
|
---|
| 733 |
|
---|
| 734 | /**
|
---|
[13580] | 735 | * Temporarily decreases the number of callers of the managed object.
|
---|
| 736 | * May only be called if #isOk() returns |true|. Note that #rc() will
|
---|
| 737 | * return E_FAIL after this method succeeds.
|
---|
[1] | 738 | */
|
---|
| 739 | void release()
|
---|
| 740 | {
|
---|
| 741 | Assert (SUCCEEDED (mRC));
|
---|
| 742 | if (SUCCEEDED (mRC))
|
---|
| 743 | {
|
---|
[3033] | 744 | if (mObj)
|
---|
| 745 | mObj->releaseCaller();
|
---|
[1] | 746 | mRC = E_FAIL;
|
---|
| 747 | }
|
---|
| 748 | }
|
---|
| 749 |
|
---|
| 750 | /**
|
---|
[13580] | 751 | * Restores the number of callers decreased by #release(). May only be
|
---|
| 752 | * called after #release().
|
---|
[1] | 753 | */
|
---|
| 754 | void add()
|
---|
| 755 | {
|
---|
| 756 | Assert (!SUCCEEDED (mRC));
|
---|
[3033] | 757 | if (mObj && !SUCCEEDED (mRC))
|
---|
[1] | 758 | mRC = mObj->addCaller (&mState, aLimited);
|
---|
| 759 | }
|
---|
| 760 |
|
---|
[13580] | 761 | /**
|
---|
| 762 | * Attaches another object to this caller instance.
|
---|
| 763 | * The previous object's caller is released before the new one is added.
|
---|
| 764 | *
|
---|
| 765 | * @param aObj New object to attach, may be @c NULL.
|
---|
| 766 | */
|
---|
| 767 | void attach (VirtualBoxBaseProto *aObj)
|
---|
| 768 | {
|
---|
| 769 | /* detect simple self-reattachment */
|
---|
| 770 | if (mObj != aObj)
|
---|
| 771 | {
|
---|
| 772 | if (mObj && SUCCEEDED (mRC))
|
---|
| 773 | release();
|
---|
| 774 | mObj = aObj;
|
---|
| 775 | add();
|
---|
| 776 | }
|
---|
| 777 | }
|
---|
| 778 |
|
---|
| 779 | /** Verbose equivalent to <tt>attach (NULL)</tt>. */
|
---|
| 780 | void detach() { attach (NULL); }
|
---|
| 781 |
|
---|
[1] | 782 | private:
|
---|
| 783 |
|
---|
| 784 | DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (AutoCallerBase)
|
---|
| 785 | DECLARE_CLS_NEW_DELETE_NOOP (AutoCallerBase)
|
---|
| 786 |
|
---|
[13580] | 787 | VirtualBoxBaseProto *mObj;
|
---|
[1] | 788 | HRESULT mRC;
|
---|
| 789 | State mState;
|
---|
| 790 | };
|
---|
| 791 |
|
---|
| 792 | /**
|
---|
[13580] | 793 | * Smart class that automatically increases the number of normal
|
---|
| 794 | * (non-limited) callers of the given VirtualBoxBase object when an instance
|
---|
| 795 | * is constructed and decreases it back when the created instance goes out
|
---|
| 796 | * of scope (i.e. gets destroyed).
|
---|
[1] | 797 | *
|
---|
[13580] | 798 | * A typical usage pattern to declare a normal method of some object (i.e. a
|
---|
| 799 | * method that is valid only when the object provides its full
|
---|
| 800 | * functionality) is:
|
---|
| 801 | * <code>
|
---|
| 802 | * STDMETHODIMP Component::Foo()
|
---|
| 803 | * {
|
---|
| 804 | * AutoCaller autoCaller (this);
|
---|
| 805 | * CheckComRCReturnRC (autoCaller.rc());
|
---|
| 806 | * ...
|
---|
| 807 | * </code>
|
---|
[1] | 808 | *
|
---|
[13580] | 809 | * Using this class is equivalent to using the AutoCallerBase template with
|
---|
| 810 | * the @a aLimited argument set to |false|, but this class is preferred
|
---|
| 811 | * because provides better self-descriptiveness.
|
---|
[1] | 812 | *
|
---|
[13580] | 813 | * See AutoCallerBase for more information about auto caller functionality.
|
---|
[1] | 814 | */
|
---|
| 815 | typedef AutoCallerBase <false> AutoCaller;
|
---|
[6935] | 816 |
|
---|
[1] | 817 | /**
|
---|
[13580] | 818 | * Smart class that automatically increases the number of limited callers of
|
---|
| 819 | * the given VirtualBoxBase object when an instance is constructed and
|
---|
| 820 | * decreases it back when the created instance goes out of scope (i.e. gets
|
---|
| 821 | * destroyed).
|
---|
[1] | 822 | *
|
---|
[13580] | 823 | * A typical usage pattern to declare a limited method of some object (i.e.
|
---|
| 824 | * a method that is valid even if the object doesn't provide its full
|
---|
| 825 | * functionality) is:
|
---|
| 826 | * <code>
|
---|
| 827 | * STDMETHODIMP Component::Bar()
|
---|
| 828 | * {
|
---|
| 829 | * AutoLimitedCaller autoCaller (this);
|
---|
| 830 | * CheckComRCReturnRC (autoCaller.rc());
|
---|
| 831 | * ...
|
---|
| 832 | * </code>
|
---|
[1] | 833 | *
|
---|
[13580] | 834 | * Using this class is equivalent to using the AutoCallerBase template with
|
---|
| 835 | * the @a aLimited argument set to |true|, but this class is preferred
|
---|
| 836 | * because provides better self-descriptiveness.
|
---|
[1] | 837 | *
|
---|
[13580] | 838 | * See AutoCallerBase for more information about auto caller functionality.
|
---|
[1] | 839 | */
|
---|
| 840 | typedef AutoCallerBase <true> AutoLimitedCaller;
|
---|
[6935] | 841 |
|
---|
[1] | 842 | protected:
|
---|
| 843 |
|
---|
| 844 | /**
|
---|
[13580] | 845 | * Smart class to enclose the state transition NotReady->InInit->Ready.
|
---|
[1] | 846 | *
|
---|
[13580] | 847 | * The purpose of this span is to protect object initialization.
|
---|
[1] | 848 | *
|
---|
[13580] | 849 | * Instances must be created as a stack-based variable taking |this| pointer
|
---|
| 850 | * as the argument at the beginning of init() methods of VirtualBoxBase
|
---|
| 851 | * subclasses. When this variable is created it automatically places the
|
---|
| 852 | * object to the InInit state.
|
---|
[1] | 853 | *
|
---|
[13580] | 854 | * When the created variable goes out of scope (i.e. gets destroyed) then,
|
---|
| 855 | * depending on the result status of this initialization span, it either
|
---|
| 856 | * places the object to Ready or Limited state or calls the object's
|
---|
| 857 | * VirtualBoxBase::uninit() method which is supposed to place the object
|
---|
| 858 | * back to the NotReady state using the AutoUninitSpan class.
|
---|
[1] | 859 | *
|
---|
[13580] | 860 | * The initial result status of the initialization span is determined by the
|
---|
| 861 | * @a aResult argument of the AutoInitSpan constructor (Result::Failed by
|
---|
| 862 | * default). Inside the initialization span, the success status can be set
|
---|
| 863 | * to Result::Succeeded using #setSucceeded(), to to Result::Limited using
|
---|
| 864 | * #setLimited() or to Result::Failed using #setFailed(). Please don't
|
---|
| 865 | * forget to set the correct success status before getting the AutoInitSpan
|
---|
[14624] | 866 | * variable destroyed (for example, by performing an early return from
|
---|
[13580] | 867 | * the init() method)!
|
---|
[1] | 868 | *
|
---|
[13580] | 869 | * Note that if an instance of this class gets constructed when the object
|
---|
| 870 | * is in the state other than NotReady, #isOk() returns |false| and methods
|
---|
| 871 | * of this class do nothing: the state transition is not performed.
|
---|
[1] | 872 | *
|
---|
[13580] | 873 | * A typical usage pattern is:
|
---|
| 874 | * <code>
|
---|
| 875 | * HRESULT Component::init()
|
---|
| 876 | * {
|
---|
| 877 | * AutoInitSpan autoInitSpan (this);
|
---|
[14579] | 878 | * AssertReturn (autoInitSpan.isOk(), E_FAIL);
|
---|
[13580] | 879 | * ...
|
---|
| 880 | * if (FAILED (rc))
|
---|
| 881 | * return rc;
|
---|
| 882 | * ...
|
---|
| 883 | * if (SUCCEEDED (rc))
|
---|
| 884 | * autoInitSpan.setSucceeded();
|
---|
| 885 | * return rc;
|
---|
| 886 | * }
|
---|
| 887 | * </code>
|
---|
| 888 | *
|
---|
| 889 | * @note Never create instances of this class outside init() methods of
|
---|
| 890 | * VirtualBoxBase subclasses and never pass anything other than |this|
|
---|
| 891 | * as the argument to the constructor!
|
---|
[1] | 892 | */
|
---|
| 893 | class AutoInitSpan
|
---|
| 894 | {
|
---|
| 895 | public:
|
---|
| 896 |
|
---|
[13580] | 897 | enum Result { Failed = 0x0, Succeeded = 0x1, Limited = 0x2 };
|
---|
[6935] | 898 |
|
---|
[13580] | 899 | AutoInitSpan (VirtualBoxBaseProto *aObj, Result aResult = Failed);
|
---|
[1] | 900 | ~AutoInitSpan();
|
---|
| 901 |
|
---|
| 902 | /**
|
---|
[13580] | 903 | * Returns |true| if this instance has been created at the right moment
|
---|
| 904 | * (when the object was in the NotReady state) and |false| otherwise.
|
---|
[1] | 905 | */
|
---|
| 906 | bool isOk() const { return mOk; }
|
---|
| 907 |
|
---|
| 908 | /**
|
---|
[13580] | 909 | * Sets the initialization status to Succeeded to indicates successful
|
---|
| 910 | * initialization. The AutoInitSpan destructor will place the managed
|
---|
| 911 | * VirtualBoxBase object to the Ready state.
|
---|
[1] | 912 | */
|
---|
[13580] | 913 | void setSucceeded() { mResult = Succeeded; }
|
---|
[1] | 914 |
|
---|
| 915 | /**
|
---|
[13580] | 916 | * Sets the initialization status to Succeeded to indicate limited
|
---|
| 917 | * (partly successful) initialization. The AutoInitSpan destructor will
|
---|
| 918 | * place the managed VirtualBoxBase object to the Limited state.
|
---|
[1] | 919 | */
|
---|
[13580] | 920 | void setLimited() { mResult = Limited; }
|
---|
[1] | 921 |
|
---|
| 922 | /**
|
---|
[13580] | 923 | * Sets the initialization status to Failure to indicates failed
|
---|
| 924 | * initialization. The AutoInitSpan destructor will place the managed
|
---|
| 925 | * VirtualBoxBase object to the InitFailed state and will automatically
|
---|
| 926 | * call its uninit() method which is supposed to place the object back
|
---|
| 927 | * to the NotReady state using AutoUninitSpan.
|
---|
[1] | 928 | */
|
---|
[13580] | 929 | void setFailed() { mResult = Failed; }
|
---|
[1] | 930 |
|
---|
[13580] | 931 | /** Returns the current initialization result. */
|
---|
| 932 | Result result() { return mResult; }
|
---|
[1] | 933 |
|
---|
| 934 | private:
|
---|
| 935 |
|
---|
| 936 | DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (AutoInitSpan)
|
---|
| 937 | DECLARE_CLS_NEW_DELETE_NOOP (AutoInitSpan)
|
---|
| 938 |
|
---|
[13580] | 939 | VirtualBoxBaseProto *mObj;
|
---|
| 940 | Result mResult : 3; // must be at least total number of bits + 1 (sign)
|
---|
[1] | 941 | bool mOk : 1;
|
---|
| 942 | };
|
---|
| 943 |
|
---|
| 944 | /**
|
---|
[13580] | 945 | * Smart class to enclose the state transition Limited->InInit->Ready.
|
---|
[1] | 946 | *
|
---|
[13580] | 947 | * The purpose of this span is to protect object re-initialization.
|
---|
[1] | 948 | *
|
---|
[13580] | 949 | * Instances must be created as a stack-based variable taking |this| pointer
|
---|
| 950 | * as the argument at the beginning of methods of VirtualBoxBase
|
---|
| 951 | * subclasses that try to re-initialize the object to bring it to the Ready
|
---|
| 952 | * state (full functionality) after partial initialization (limited
|
---|
| 953 | * functionality). When this variable is created, it automatically places
|
---|
| 954 | * the object to the InInit state.
|
---|
[1] | 955 | *
|
---|
[13580] | 956 | * When the created variable goes out of scope (i.e. gets destroyed),
|
---|
| 957 | * depending on the success status of this initialization span, it either
|
---|
| 958 | * places the object to the Ready state or brings it back to the Limited
|
---|
| 959 | * state.
|
---|
[1] | 960 | *
|
---|
[13580] | 961 | * The initial success status of the re-initialization span is |false|. In
|
---|
| 962 | * order to make it successful, #setSucceeded() must be called before the
|
---|
| 963 | * instance is destroyed.
|
---|
[1] | 964 | *
|
---|
[13580] | 965 | * Note that if an instance of this class gets constructed when the object
|
---|
| 966 | * is in the state other than Limited, #isOk() returns |false| and methods
|
---|
| 967 | * of this class do nothing: the state transition is not performed.
|
---|
[1] | 968 | *
|
---|
[13580] | 969 | * A typical usage pattern is:
|
---|
| 970 | * <code>
|
---|
| 971 | * HRESULT Component::reinit()
|
---|
| 972 | * {
|
---|
| 973 | * AutoReinitSpan autoReinitSpan (this);
|
---|
[14579] | 974 | * AssertReturn (autoReinitSpan.isOk(), E_FAIL);
|
---|
[13580] | 975 | * ...
|
---|
| 976 | * if (FAILED (rc))
|
---|
| 977 | * return rc;
|
---|
| 978 | * ...
|
---|
| 979 | * if (SUCCEEDED (rc))
|
---|
| 980 | * autoReinitSpan.setSucceeded();
|
---|
| 981 | * return rc;
|
---|
| 982 | * }
|
---|
| 983 | * </code>
|
---|
| 984 | *
|
---|
| 985 | * @note Never create instances of this class outside re-initialization
|
---|
| 986 | * methods of VirtualBoxBase subclasses and never pass anything other than
|
---|
| 987 | * |this| as the argument to the constructor!
|
---|
[1] | 988 | */
|
---|
[13580] | 989 | class AutoReinitSpan
|
---|
[1] | 990 | {
|
---|
| 991 | public:
|
---|
| 992 |
|
---|
[13580] | 993 | AutoReinitSpan (VirtualBoxBaseProto *aObj);
|
---|
| 994 | ~AutoReinitSpan();
|
---|
[1] | 995 |
|
---|
| 996 | /**
|
---|
[13580] | 997 | * Returns |true| if this instance has been created at the right moment
|
---|
| 998 | * (when the object was in the Limited state) and |false| otherwise.
|
---|
[1] | 999 | */
|
---|
| 1000 | bool isOk() const { return mOk; }
|
---|
| 1001 |
|
---|
| 1002 | /**
|
---|
[13580] | 1003 | * Sets the re-initialization status to Succeeded to indicates
|
---|
| 1004 | * successful re-initialization. The AutoReinitSpan destructor will place
|
---|
| 1005 | * the managed VirtualBoxBase object to the Ready state.
|
---|
[1] | 1006 | */
|
---|
| 1007 | void setSucceeded() { mSucceeded = true; }
|
---|
| 1008 |
|
---|
| 1009 | private:
|
---|
| 1010 |
|
---|
[13580] | 1011 | DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (AutoReinitSpan)
|
---|
| 1012 | DECLARE_CLS_NEW_DELETE_NOOP (AutoReinitSpan)
|
---|
[1] | 1013 |
|
---|
[13580] | 1014 | VirtualBoxBaseProto *mObj;
|
---|
[1] | 1015 | bool mSucceeded : 1;
|
---|
| 1016 | bool mOk : 1;
|
---|
| 1017 | };
|
---|
| 1018 |
|
---|
| 1019 | /**
|
---|
[13580] | 1020 | * Smart class to enclose the state transition Ready->InUnnit->NotReady,
|
---|
| 1021 | * InitFailed->InUnnit->NotReady or WillUninit->InUnnit->NotReady.
|
---|
[1] | 1022 | *
|
---|
[13580] | 1023 | * The purpose of this span is to protect object uninitialization.
|
---|
[1] | 1024 | *
|
---|
[13580] | 1025 | * Instances must be created as a stack-based variable taking |this| pointer
|
---|
| 1026 | * as the argument at the beginning of uninit() methods of VirtualBoxBase
|
---|
| 1027 | * subclasses. When this variable is created it automatically places the
|
---|
| 1028 | * object to the InUninit state, unless it is already in the NotReady state
|
---|
| 1029 | * as indicated by #uninitDone() returning |true|. In the latter case, the
|
---|
| 1030 | * uninit() method must immediately return because there should be nothing
|
---|
| 1031 | * to uninitialize.
|
---|
[1] | 1032 | *
|
---|
[13580] | 1033 | * When this variable goes out of scope (i.e. gets destroyed), it places the
|
---|
| 1034 | * object to NotReady state.
|
---|
[1] | 1035 | *
|
---|
[13580] | 1036 | * A typical usage pattern is:
|
---|
| 1037 | * <code>
|
---|
| 1038 | * void Component::uninit()
|
---|
| 1039 | * {
|
---|
| 1040 | * AutoUninitSpan autoUninitSpan (this);
|
---|
| 1041 | * if (autoUninitSpan.uninitDone())
|
---|
[14624] | 1042 | * return;
|
---|
[13580] | 1043 | * ...
|
---|
| 1044 | * }
|
---|
| 1045 | * </code>
|
---|
| 1046 | *
|
---|
| 1047 | * @note The constructor of this class blocks the current thread execution
|
---|
| 1048 | * until the number of callers added to the object using #addCaller()
|
---|
| 1049 | * or AutoCaller drops to zero. For this reason, it is forbidden to
|
---|
| 1050 | * create instances of this class (or call uninit()) within the
|
---|
| 1051 | * AutoCaller or #addCaller() scope because it is a guaranteed
|
---|
| 1052 | * deadlock.
|
---|
| 1053 | *
|
---|
| 1054 | * @note Never create instances of this class outside uninit() methods and
|
---|
| 1055 | * never pass anything other than |this| as the argument to the
|
---|
| 1056 | * constructor!
|
---|
[1] | 1057 | */
|
---|
| 1058 | class AutoUninitSpan
|
---|
| 1059 | {
|
---|
| 1060 | public:
|
---|
| 1061 |
|
---|
[13580] | 1062 | AutoUninitSpan (VirtualBoxBaseProto *aObj);
|
---|
[1] | 1063 | ~AutoUninitSpan();
|
---|
| 1064 |
|
---|
| 1065 | /** |true| when uninit() is called as a result of init() failure */
|
---|
| 1066 | bool initFailed() { return mInitFailed; }
|
---|
| 1067 |
|
---|
| 1068 | /** |true| when uninit() has already been called (so the object is NotReady) */
|
---|
| 1069 | bool uninitDone() { return mUninitDone; }
|
---|
| 1070 |
|
---|
| 1071 | private:
|
---|
| 1072 |
|
---|
| 1073 | DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (AutoUninitSpan)
|
---|
| 1074 | DECLARE_CLS_NEW_DELETE_NOOP (AutoUninitSpan)
|
---|
| 1075 |
|
---|
[13580] | 1076 | VirtualBoxBaseProto *mObj;
|
---|
[1] | 1077 | bool mInitFailed : 1;
|
---|
| 1078 | bool mUninitDone : 1;
|
---|
| 1079 | };
|
---|
| 1080 |
|
---|
[7992] | 1081 | /**
|
---|
[13580] | 1082 | * Smart class to enclose the state transition Ready->MayUninit->NotReady or
|
---|
| 1083 | * Ready->MayUninit->WillUninit.
|
---|
| 1084 | *
|
---|
| 1085 | * The purpose of this span is to safely check if unintialization is
|
---|
| 1086 | * possible at the given moment and seamlessly perform it if so.
|
---|
| 1087 | *
|
---|
| 1088 | * Instances must be created as a stack-based variable taking |this| pointer
|
---|
| 1089 | * as the argument at the beginning of methods of VirtualBoxBase
|
---|
| 1090 | * subclasses that want to uninitialize the object if a necessary set of
|
---|
| 1091 | * criteria is met and leave it Ready otherwise.
|
---|
| 1092 | *
|
---|
| 1093 | * When this variable is created it automatically places the object to the
|
---|
| 1094 | * MayUninit state if it is Ready, does nothing but returns |true| in
|
---|
| 1095 | * response to #alreadyInProgress() if it is already in MayUninit, or
|
---|
| 1096 | * returns a failure in response to #rc() in any other case. The example
|
---|
| 1097 | * below shows how the user must react in latter two cases.
|
---|
| 1098 | *
|
---|
| 1099 | * When this variable goes out of scope (i.e. gets destroyed), it places the
|
---|
| 1100 | * object back to Ready state unless #acceptUninit() is called in which case
|
---|
| 1101 | * the object is placed to WillUninit state and uninit() is immediately
|
---|
| 1102 | * called after that.
|
---|
| 1103 | *
|
---|
| 1104 | * A typical usage pattern is:
|
---|
| 1105 | * <code>
|
---|
| 1106 | * void Component::uninit()
|
---|
| 1107 | * {
|
---|
| 1108 | * AutoMayUninitSpan mayUninitSpan (this);
|
---|
| 1109 | * CheckComRCReturnRC (mayUninitSpan.rc());
|
---|
| 1110 | * if (mayUninitSpan.alreadyInProgress())
|
---|
| 1111 | * return S_OK;
|
---|
| 1112 | * ...
|
---|
| 1113 | * if (FAILED (rc))
|
---|
| 1114 | * return rc; // will go back to Ready
|
---|
| 1115 | * ...
|
---|
| 1116 | * if (SUCCEEDED (rc))
|
---|
| 1117 | * mayUninitSpan.acceptUninit(); // will call uninit()
|
---|
| 1118 | * return rc;
|
---|
| 1119 | * }
|
---|
| 1120 | * </code>
|
---|
| 1121 | *
|
---|
| 1122 | * @note The constructor of this class blocks the current thread execution
|
---|
| 1123 | * until the number of callers added to the object using #addCaller()
|
---|
| 1124 | * or AutoCaller drops to zero. For this reason, it is forbidden to
|
---|
| 1125 | * create instances of this class (or call uninit()) within the
|
---|
| 1126 | * AutoCaller or #addCaller() scope because it is a guaranteed
|
---|
| 1127 | * deadlock.
|
---|
| 1128 | */
|
---|
| 1129 | class AutoMayUninitSpan
|
---|
| 1130 | {
|
---|
| 1131 | public:
|
---|
| 1132 |
|
---|
| 1133 | AutoMayUninitSpan (VirtualBoxBaseProto *aObj);
|
---|
| 1134 | ~AutoMayUninitSpan();
|
---|
| 1135 |
|
---|
| 1136 | /**
|
---|
| 1137 | * Returns a failure if the AutoMayUninitSpan variable was constructed
|
---|
| 1138 | * at an improper time. If there is a failure, do nothing but return
|
---|
| 1139 | * it to the caller.
|
---|
| 1140 | */
|
---|
| 1141 | HRESULT rc() { return mRC; }
|
---|
| 1142 |
|
---|
| 1143 | /**
|
---|
| 1144 | * Returns |true| if AutoMayUninitSpan is already in progress on some
|
---|
| 1145 | * other thread. If it's the case, do nothing but return S_OK to
|
---|
| 1146 | * the caller.
|
---|
| 1147 | */
|
---|
| 1148 | bool alreadyInProgress() { return mAlreadyInProgress; }
|
---|
| 1149 |
|
---|
| 1150 | /*
|
---|
| 1151 | * Accepts uninitialization and causes the destructor to go to
|
---|
| 1152 | * WillUninit state and call uninit() afterwards.
|
---|
| 1153 | */
|
---|
| 1154 | void acceptUninit() { mAcceptUninit = true; }
|
---|
| 1155 |
|
---|
| 1156 | private:
|
---|
| 1157 |
|
---|
| 1158 | DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (AutoMayUninitSpan)
|
---|
| 1159 | DECLARE_CLS_NEW_DELETE_NOOP (AutoMayUninitSpan)
|
---|
| 1160 |
|
---|
| 1161 | VirtualBoxBaseProto *mObj;
|
---|
| 1162 |
|
---|
| 1163 | HRESULT mRC;
|
---|
| 1164 | bool mAlreadyInProgress : 1;
|
---|
| 1165 | bool mAcceptUninit : 1;
|
---|
| 1166 | };
|
---|
| 1167 |
|
---|
| 1168 | /**
|
---|
[7992] | 1169 | * Returns a lock handle used to protect the primary state fields (used by
|
---|
| 1170 | * #addCaller(), AutoInitSpan, AutoUninitSpan, etc.). Only intended to be
|
---|
| 1171 | * used for similar purposes in subclasses. WARNING: NO any other locks may
|
---|
| 1172 | * be requested while holding this lock!
|
---|
| 1173 | */
|
---|
| 1174 | WriteLockHandle *stateLockHandle() { return &mStateLock; }
|
---|
| 1175 |
|
---|
[1] | 1176 | private:
|
---|
| 1177 |
|
---|
| 1178 | void setState (State aState)
|
---|
| 1179 | {
|
---|
| 1180 | Assert (mState != aState);
|
---|
| 1181 | mState = aState;
|
---|
| 1182 | mStateChangeThread = RTThreadSelf();
|
---|
| 1183 | }
|
---|
| 1184 |
|
---|
| 1185 | /** Primary state of this object */
|
---|
| 1186 | State mState;
|
---|
| 1187 | /** Thread that caused the last state change */
|
---|
| 1188 | RTTHREAD mStateChangeThread;
|
---|
| 1189 | /** Total number of active calls to this object */
|
---|
| 1190 | unsigned mCallers;
|
---|
[13580] | 1191 | /** Posted when the number of callers drops to zero */
|
---|
[1] | 1192 | RTSEMEVENT mZeroCallersSem;
|
---|
[13580] | 1193 | /** Posted when the object goes from InInit/InUninit to some other state */
|
---|
| 1194 | RTSEMEVENTMULTI mInitUninitSem;
|
---|
| 1195 | /** Number of threads waiting for mInitUninitDoneSem */
|
---|
| 1196 | unsigned mInitUninitWaiters;
|
---|
[1] | 1197 |
|
---|
| 1198 | /** Protects access to state related data members */
|
---|
[7992] | 1199 | WriteLockHandle mStateLock;
|
---|
[1] | 1200 |
|
---|
| 1201 | /** User-level object lock for subclasses */
|
---|
[7992] | 1202 | mutable RWLockHandle *mObjectLock;
|
---|
[1] | 1203 | };
|
---|
| 1204 |
|
---|
[13580] | 1205 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 1206 |
|
---|
[1] | 1207 | /**
|
---|
| 1208 | * This macro adds the error info support to methods of the VirtualBoxBase
|
---|
| 1209 | * class (by overriding them). Place it to the public section of the
|
---|
| 1210 | * VirtualBoxBase subclass and the following methods will set the extended
|
---|
| 1211 | * error info in case of failure instead of just returning the result code:
|
---|
| 1212 | *
|
---|
| 1213 | * <ul>
|
---|
| 1214 | * <li>VirtualBoxBase::addCaller()
|
---|
| 1215 | * </ul>
|
---|
| 1216 | *
|
---|
| 1217 | * @note The given VirtualBoxBase subclass must also inherit from both
|
---|
| 1218 | * VirtualBoxSupportErrorInfoImpl and VirtualBoxSupportTranslation templates!
|
---|
| 1219 | *
|
---|
| 1220 | * @param C VirtualBoxBase subclass to add the error info support to
|
---|
| 1221 | */
|
---|
| 1222 | #define VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(C) \
|
---|
[13580] | 1223 | virtual HRESULT addCaller (VirtualBoxBaseProto::State *aState = NULL, \
|
---|
[1] | 1224 | bool aLimited = false) \
|
---|
| 1225 | { \
|
---|
[13580] | 1226 | VirtualBoxBaseProto::State state; \
|
---|
| 1227 | HRESULT rc = VirtualBoxBaseProto::addCaller (&state, aLimited); \
|
---|
[1] | 1228 | if (FAILED (rc)) \
|
---|
| 1229 | { \
|
---|
[13580] | 1230 | if (state == VirtualBoxBaseProto::Limited) \
|
---|
[14624] | 1231 | rc = setError (rc, tr ("The object functionality is limited")); \
|
---|
[1] | 1232 | else \
|
---|
| 1233 | rc = setError (rc, tr ("The object is not ready")); \
|
---|
| 1234 | } \
|
---|
| 1235 | if (aState) \
|
---|
| 1236 | *aState = state; \
|
---|
| 1237 | return rc; \
|
---|
| 1238 | } \
|
---|
| 1239 |
|
---|
| 1240 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 1241 |
|
---|
| 1242 | /// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
|
---|
[13580] | 1243 | class ATL_NO_VTABLE VirtualBoxBase
|
---|
| 1244 | : virtual public VirtualBoxBaseProto
|
---|
| 1245 | #if !defined (VBOX_WITH_XPCOM)
|
---|
| 1246 | , public CComObjectRootEx <CComMultiThreadModel>
|
---|
| 1247 | #else
|
---|
| 1248 | , public CComObjectRootEx
|
---|
| 1249 | #endif
|
---|
[1] | 1250 | {
|
---|
| 1251 |
|
---|
| 1252 | public:
|
---|
| 1253 | VirtualBoxBase()
|
---|
| 1254 | {
|
---|
| 1255 | mReady = false;
|
---|
| 1256 | }
|
---|
| 1257 | virtual ~VirtualBoxBase()
|
---|
| 1258 | {
|
---|
| 1259 | }
|
---|
| 1260 |
|
---|
| 1261 | /**
|
---|
| 1262 | * Virtual unintialization method. Called during parent object's
|
---|
| 1263 | * uninitialization, if the given subclass instance is a dependent child of
|
---|
[14624] | 1264 | * a class derived from VirtualBoxBaseWithChildren (@sa
|
---|
[1] | 1265 | * VirtualBoxBaseWithChildren::addDependentChild). In this case, this
|
---|
[14624] | 1266 | * method's implementation must call setReady (false),
|
---|
[1] | 1267 | */
|
---|
| 1268 | virtual void uninit() {}
|
---|
| 1269 |
|
---|
| 1270 |
|
---|
| 1271 | // sets the ready state of the object
|
---|
| 1272 | void setReady(bool isReady)
|
---|
| 1273 | {
|
---|
| 1274 | mReady = isReady;
|
---|
| 1275 | }
|
---|
| 1276 | // get the ready state of the object
|
---|
| 1277 | bool isReady()
|
---|
| 1278 | {
|
---|
| 1279 | return mReady;
|
---|
| 1280 | }
|
---|
| 1281 |
|
---|
| 1282 | static const char *translate (const char *context, const char *sourceText,
|
---|
| 1283 | const char *comment = 0);
|
---|
| 1284 |
|
---|
| 1285 | private:
|
---|
| 1286 |
|
---|
| 1287 | // flag determining whether an object is ready
|
---|
| 1288 | // for usage, i.e. methods may be called
|
---|
| 1289 | bool mReady;
|
---|
| 1290 | // mutex semaphore to lock the object
|
---|
| 1291 | };
|
---|
| 1292 |
|
---|
| 1293 | /**
|
---|
| 1294 | * Temporary class to disable deprecated methods of VirtualBoxBase.
|
---|
| 1295 | * Can be used as a base for components that are completely switched to
|
---|
[13580] | 1296 | * the new locking scheme (VirtualBoxBaseProto).
|
---|
[1] | 1297 | *
|
---|
| 1298 | * @todo remove after we switch to VirtualBoxBaseNEXT completely.
|
---|
| 1299 | */
|
---|
| 1300 | class VirtualBoxBaseNEXT : public VirtualBoxBase
|
---|
| 1301 | {
|
---|
| 1302 | private:
|
---|
| 1303 |
|
---|
| 1304 | void lock();
|
---|
| 1305 | void unlock();
|
---|
| 1306 | void setReady (bool isReady);
|
---|
| 1307 | bool isReady();
|
---|
| 1308 | };
|
---|
| 1309 |
|
---|
| 1310 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 1311 |
|
---|
[13580] | 1312 | /** Helper for VirtualBoxSupportTranslation. */
|
---|
[1] | 1313 | class VirtualBoxSupportTranslationBase
|
---|
| 1314 | {
|
---|
| 1315 | protected:
|
---|
[13580] | 1316 | static bool cutClassNameFrom__PRETTY_FUNCTION__ (char *aPrettyFunctionName);
|
---|
[1] | 1317 | };
|
---|
| 1318 |
|
---|
| 1319 | /**
|
---|
[13580] | 1320 | * The VirtualBoxSupportTranslation template implements the NLS string
|
---|
| 1321 | * translation support for the given class.
|
---|
[1] | 1322 | *
|
---|
[13580] | 1323 | * Translation support is provided by the static #tr() function. This function,
|
---|
| 1324 | * given a string in UTF-8 encoding, looks up for a translation of the given
|
---|
| 1325 | * string by calling the VirtualBoxBase::translate() global function which
|
---|
| 1326 | * receives the name of the enclosing class ("context of translation") as the
|
---|
| 1327 | * additional argument and returns a translated string based on the currently
|
---|
| 1328 | * active language.
|
---|
[1] | 1329 | *
|
---|
[13580] | 1330 | * @param C Class that needs to support the string translation.
|
---|
| 1331 | *
|
---|
| 1332 | * @note Every class that wants to use the #tr() function in its own methods
|
---|
| 1333 | * must inherit from this template, regardless of whether its base class
|
---|
| 1334 | * (if any) inherits from it or not. Otherwise, the translation service
|
---|
| 1335 | * will not work correctly. However, the declaration of the derived
|
---|
| 1336 | * class must contain
|
---|
| 1337 | * the <tt>COM_SUPPORTTRANSLATION_OVERRIDE (<ClassName>)</tt> macro if one
|
---|
| 1338 | * of its base classes also inherits from this template (to resolve the
|
---|
| 1339 | * ambiguity of the #tr() function).
|
---|
[1] | 1340 | */
|
---|
| 1341 | template <class C>
|
---|
| 1342 | class VirtualBoxSupportTranslation : virtual protected VirtualBoxSupportTranslationBase
|
---|
| 1343 | {
|
---|
| 1344 | public:
|
---|
| 1345 |
|
---|
| 1346 | /**
|
---|
[13580] | 1347 | * Translates the given text string by calling VirtualBoxBase::translate()
|
---|
| 1348 | * and passing the name of the C class as the first argument ("context of
|
---|
| 1349 | * translation") See VirtualBoxBase::translate() for more info.
|
---|
[1] | 1350 | *
|
---|
[13580] | 1351 | * @param aSourceText String to translate.
|
---|
| 1352 | * @param aComment Comment to the string to resolve possible
|
---|
| 1353 | * ambiguities (NULL means no comment).
|
---|
[1] | 1354 | *
|
---|
[13580] | 1355 | * @return Translated version of the source string in UTF-8 encoding, or
|
---|
| 1356 | * the source string itself if the translation is not found in the
|
---|
[14624] | 1357 | * specified context.
|
---|
[1] | 1358 | */
|
---|
[13580] | 1359 | inline static const char *tr (const char *aSourceText,
|
---|
| 1360 | const char *aComment = NULL)
|
---|
[1] | 1361 | {
|
---|
[13580] | 1362 | return VirtualBoxBase::translate (className(), aSourceText, aComment);
|
---|
[1] | 1363 | }
|
---|
| 1364 |
|
---|
| 1365 | protected:
|
---|
| 1366 |
|
---|
[13580] | 1367 | static const char *className()
|
---|
[1] | 1368 | {
|
---|
| 1369 | static char fn [sizeof (__PRETTY_FUNCTION__) + 1];
|
---|
[13580] | 1370 | if (!sClassName)
|
---|
[1] | 1371 | {
|
---|
| 1372 | strcpy (fn, __PRETTY_FUNCTION__);
|
---|
| 1373 | cutClassNameFrom__PRETTY_FUNCTION__ (fn);
|
---|
[13580] | 1374 | sClassName = fn;
|
---|
[1] | 1375 | }
|
---|
[13580] | 1376 | return sClassName;
|
---|
[1] | 1377 | }
|
---|
| 1378 |
|
---|
| 1379 | private:
|
---|
| 1380 |
|
---|
[13580] | 1381 | static const char *sClassName;
|
---|
[1] | 1382 | };
|
---|
| 1383 |
|
---|
| 1384 | template <class C>
|
---|
[13580] | 1385 | const char *VirtualBoxSupportTranslation <C>::sClassName = NULL;
|
---|
[1] | 1386 |
|
---|
| 1387 | /**
|
---|
[13580] | 1388 | * This macro must be invoked inside the public section of the declaration of
|
---|
| 1389 | * the class inherited from the VirtualBoxSupportTranslation template in case
|
---|
| 1390 | * if one of its other base classes also inherits from that template. This is
|
---|
| 1391 | * necessary to resolve the ambiguity of the #tr() function.
|
---|
[1] | 1392 | *
|
---|
[13580] | 1393 | * @param C Class that inherits the VirtualBoxSupportTranslation template
|
---|
| 1394 | * more than once (through its other base clases).
|
---|
[1] | 1395 | */
|
---|
| 1396 | #define VIRTUALBOXSUPPORTTRANSLATION_OVERRIDE(C) \
|
---|
[13580] | 1397 | inline static const char *tr (const char *aSourceText, \
|
---|
| 1398 | const char *aComment = NULL) \
|
---|
[1] | 1399 | { \
|
---|
[13580] | 1400 | return VirtualBoxSupportTranslation <C>::tr (aSourceText, aComment); \
|
---|
[1] | 1401 | }
|
---|
| 1402 |
|
---|
| 1403 | /**
|
---|
[13580] | 1404 | * Dummy macro that is used to shut down Qt's lupdate tool warnings in some
|
---|
| 1405 | * situations. This macro needs to be present inside (better at the very
|
---|
| 1406 | * beginning) of the declaration of the class that inherits from
|
---|
| 1407 | * VirtualBoxSupportTranslation template, to make lupdate happy.
|
---|
[1] | 1408 | */
|
---|
| 1409 | #define Q_OBJECT
|
---|
| 1410 |
|
---|
| 1411 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 1412 |
|
---|
| 1413 | /**
|
---|
| 1414 | * Helper for the VirtualBoxSupportErrorInfoImpl template.
|
---|
| 1415 | */
|
---|
[13580] | 1416 | /// @todo switch to com::SupportErrorInfo* and remove
|
---|
[1] | 1417 | class VirtualBoxSupportErrorInfoImplBase
|
---|
| 1418 | {
|
---|
[2672] | 1419 | static HRESULT setErrorInternal (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1420 | const Bstr &aComponent, const Bstr &aText,
|
---|
[8709] | 1421 | bool aWarning, bool aLogIt);
|
---|
[2672] | 1422 |
|
---|
[1] | 1423 | protected:
|
---|
| 1424 |
|
---|
[6964] | 1425 | /**
|
---|
[13580] | 1426 | * The MultiResult class is a com::FWResult enhancement that also acts as a
|
---|
[6964] | 1427 | * switch to turn on multi-error mode for #setError() or #setWarning()
|
---|
| 1428 | * calls.
|
---|
| 1429 | *
|
---|
| 1430 | * When an instance of this class is created, multi-error mode is turned on
|
---|
| 1431 | * for the current thread and the turn-on counter is increased by one. In
|
---|
| 1432 | * multi-error mode, a call to #setError() or #setWarning() does not
|
---|
| 1433 | * overwrite the current error or warning info object possibly set on the
|
---|
| 1434 | * current thread by other method calls, but instead it stores this old
|
---|
| 1435 | * object in the IVirtualBoxErrorInfo::next attribute of the new error
|
---|
| 1436 | * object being set.
|
---|
| 1437 | *
|
---|
| 1438 | * This way, error/warning objects are stacked together and form a chain of
|
---|
| 1439 | * errors where the most recent error is the first one retrieved by the
|
---|
[14624] | 1440 | * calling party, the preceding error is what the
|
---|
[6964] | 1441 | * IVirtualBoxErrorInfo::next attribute of the first error points to, and so
|
---|
[14624] | 1442 | * on, up to the first error or warning occurred which is the last in the
|
---|
[6964] | 1443 | * chain. See IVirtualBoxErrorInfo documentation for more info.
|
---|
| 1444 | *
|
---|
| 1445 | * When the instance of the MultiResult class goes out of scope and gets
|
---|
| 1446 | * destroyed, it automatically decreases the turn-on counter by one. If
|
---|
| 1447 | * the counter drops to zero, multi-error mode for the current thread is
|
---|
| 1448 | * turned off and the thread switches back to single-error mode where every
|
---|
| 1449 | * next error or warning object overwrites the previous one.
|
---|
| 1450 | *
|
---|
[14624] | 1451 | * Note that the caller of a COM method uses a non-S_OK result code to
|
---|
[6964] | 1452 | * decide if the method has returned an error (negative codes) or a warning
|
---|
| 1453 | * (positive non-zero codes) and will query extended error info only in
|
---|
| 1454 | * these two cases. However, since multi-error mode implies that the method
|
---|
| 1455 | * doesn't return control return to the caller immediately after the first
|
---|
| 1456 | * error or warning but continues its execution, the functionality provided
|
---|
[13580] | 1457 | * by the base com::FWResult class becomes very useful because it allows to
|
---|
[14624] | 1458 | * preserve the error or the warning result code even if it is later assigned
|
---|
[13580] | 1459 | * a S_OK value multiple times. See com::FWResult for details.
|
---|
[6964] | 1460 | *
|
---|
| 1461 | * Here is the typical usage pattern:
|
---|
| 1462 | * <code>
|
---|
| 1463 |
|
---|
| 1464 | HRESULT Bar::method()
|
---|
| 1465 | {
|
---|
| 1466 | // assume multi-errors are turned off here...
|
---|
| 1467 |
|
---|
| 1468 | if (something)
|
---|
| 1469 | {
|
---|
| 1470 | // Turn on multi-error mode and make sure severity is preserved
|
---|
| 1471 | MultiResult rc = foo->method1();
|
---|
| 1472 |
|
---|
| 1473 | // return on fatal error, but continue on warning or on success
|
---|
| 1474 | CheckComRCReturnRC (rc);
|
---|
| 1475 |
|
---|
| 1476 | rc = foo->method2();
|
---|
| 1477 | // no matter what result, stack it and continue
|
---|
| 1478 |
|
---|
| 1479 | // ...
|
---|
| 1480 |
|
---|
| 1481 | // return the last worst result code (it will be preserved even if
|
---|
| 1482 | // foo->method2() returns S_OK.
|
---|
| 1483 | return rc;
|
---|
| 1484 | }
|
---|
| 1485 |
|
---|
| 1486 | // multi-errors are turned off here again...
|
---|
| 1487 |
|
---|
| 1488 | return S_OK;
|
---|
| 1489 | }
|
---|
| 1490 |
|
---|
| 1491 | * </code>
|
---|
| 1492 | *
|
---|
| 1493 | *
|
---|
| 1494 | * @note This class is intended to be instantiated on the stack, therefore
|
---|
| 1495 | * You cannot create them using new(). Although it is possible to copy
|
---|
| 1496 | * instances of MultiResult or return them by value, please never do
|
---|
[13580] | 1497 | * that as it is breaks the class semantics (and will assert).
|
---|
[6964] | 1498 | */
|
---|
[13580] | 1499 | class MultiResult : public com::FWResult
|
---|
[6964] | 1500 | {
|
---|
| 1501 | public:
|
---|
| 1502 |
|
---|
| 1503 | /**
|
---|
[13580] | 1504 | * @copydoc com::FWResult::FWResult().
|
---|
[6964] | 1505 | */
|
---|
[13580] | 1506 | MultiResult (HRESULT aRC = E_FAIL) : FWResult (aRC) { init(); }
|
---|
[6964] | 1507 |
|
---|
[13580] | 1508 | MultiResult (const MultiResult &aThat) : FWResult (aThat)
|
---|
[6964] | 1509 | {
|
---|
| 1510 | /* We need this copy constructor only for GCC that wants to have
|
---|
| 1511 | * it in case of expressions like |MultiResult rc = E_FAIL;|. But
|
---|
| 1512 | * we assert since the optimizer should actually avoid the
|
---|
[14624] | 1513 | * temporary and call the other constructor directly instead. */
|
---|
[6964] | 1514 | AssertFailed();
|
---|
| 1515 | init();
|
---|
| 1516 | }
|
---|
| 1517 |
|
---|
| 1518 | ~MultiResult();
|
---|
| 1519 |
|
---|
| 1520 | MultiResult &operator= (HRESULT aRC)
|
---|
| 1521 | {
|
---|
[13580] | 1522 | com::FWResult::operator= (aRC);
|
---|
[6964] | 1523 | return *this;
|
---|
| 1524 | }
|
---|
| 1525 |
|
---|
| 1526 | MultiResult &operator= (const MultiResult &aThat)
|
---|
| 1527 | {
|
---|
| 1528 | /* We need this copy constructor only for GCC that wants to have
|
---|
| 1529 | * it in case of expressions like |MultiResult rc = E_FAIL;|. But
|
---|
| 1530 | * we assert since the optimizer should actually avoid the
|
---|
[14624] | 1531 | * temporary and call the other constructor directly instead. */
|
---|
[6964] | 1532 | AssertFailed();
|
---|
[13580] | 1533 | com::FWResult::operator= (aThat);
|
---|
[6964] | 1534 | return *this;
|
---|
| 1535 | }
|
---|
| 1536 |
|
---|
| 1537 | private:
|
---|
| 1538 |
|
---|
| 1539 | DECLARE_CLS_NEW_DELETE_NOOP (MultiResult)
|
---|
| 1540 |
|
---|
| 1541 | void init();
|
---|
| 1542 |
|
---|
| 1543 | static RTTLS sCounter;
|
---|
| 1544 |
|
---|
| 1545 | friend class VirtualBoxSupportErrorInfoImplBase;
|
---|
| 1546 | };
|
---|
| 1547 |
|
---|
[6935] | 1548 | static HRESULT setError (HRESULT aResultCode, const GUID &aIID,
|
---|
[8709] | 1549 | const Bstr &aComponent,
|
---|
| 1550 | const Bstr &aText,
|
---|
| 1551 | bool aLogIt = true)
|
---|
[2672] | 1552 | {
|
---|
| 1553 | return setErrorInternal (aResultCode, aIID, aComponent, aText,
|
---|
[8709] | 1554 | false /* aWarning */, aLogIt);
|
---|
[2672] | 1555 | }
|
---|
[1] | 1556 |
|
---|
[6964] | 1557 | static HRESULT setWarning (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1558 | const Bstr &aComponent,
|
---|
| 1559 | const Bstr &aText)
|
---|
[2672] | 1560 | {
|
---|
| 1561 | return setErrorInternal (aResultCode, aIID, aComponent, aText,
|
---|
[8709] | 1562 | true /* aWarning */, true /* aLogIt */);
|
---|
[2672] | 1563 | }
|
---|
[1] | 1564 |
|
---|
[2672] | 1565 | static HRESULT setError (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1566 | const Bstr &aComponent,
|
---|
[8709] | 1567 | const char *aText, va_list aArgs, bool aLogIt = true)
|
---|
[1] | 1568 | {
|
---|
[2672] | 1569 | return setErrorInternal (aResultCode, aIID, aComponent,
|
---|
[4134] | 1570 | Utf8StrFmtVA (aText, aArgs),
|
---|
[8709] | 1571 | false /* aWarning */, aLogIt);
|
---|
[2672] | 1572 | }
|
---|
[1] | 1573 |
|
---|
[6964] | 1574 | static HRESULT setWarning (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1575 | const Bstr &aComponent,
|
---|
| 1576 | const char *aText, va_list aArgs)
|
---|
[2672] | 1577 | {
|
---|
| 1578 | return setErrorInternal (aResultCode, aIID, aComponent,
|
---|
[4134] | 1579 | Utf8StrFmtVA (aText, aArgs),
|
---|
[8709] | 1580 | true /* aWarning */, true /* aLogIt */);
|
---|
[1] | 1581 | }
|
---|
| 1582 | };
|
---|
| 1583 |
|
---|
| 1584 | /**
|
---|
| 1585 | * This template implements ISupportErrorInfo for the given component class
|
---|
| 1586 | * and provides the #setError() method to conveniently set the error information
|
---|
| 1587 | * from within interface methods' implementations.
|
---|
| 1588 | *
|
---|
| 1589 | * On Windows, the template argument must define a COM interface map using
|
---|
| 1590 | * BEGIN_COM_MAP / END_COM_MAP macros and this map must contain a
|
---|
| 1591 | * COM_INTERFACE_ENTRY(ISupportErrorInfo) definition. All interface entries
|
---|
| 1592 | * that follow it will be considered to support IErrorInfo, i.e. the
|
---|
| 1593 | * InterfaceSupportsErrorInfo() implementation will return S_OK for the
|
---|
| 1594 | * corresponding IID.
|
---|
| 1595 | *
|
---|
| 1596 | * On all platforms, the template argument must also define the following
|
---|
| 1597 | * method: |public static const wchar_t *C::getComponentName()|. See
|
---|
| 1598 | * #setError (HRESULT, const char *, ...) for a description on how it is
|
---|
| 1599 | * used.
|
---|
| 1600 | *
|
---|
| 1601 | * @param C
|
---|
| 1602 | * component class that implements one or more COM interfaces
|
---|
| 1603 | * @param I
|
---|
| 1604 | * default interface for the component. This interface's IID is used
|
---|
| 1605 | * by the shortest form of #setError, for convenience.
|
---|
| 1606 | */
|
---|
[13580] | 1607 | /// @todo switch to com::SupportErrorInfo* and remove
|
---|
[1] | 1608 | template <class C, class I>
|
---|
| 1609 | class ATL_NO_VTABLE VirtualBoxSupportErrorInfoImpl
|
---|
| 1610 | : protected VirtualBoxSupportErrorInfoImplBase
|
---|
[6935] | 1611 | #if !defined (VBOX_WITH_XPCOM)
|
---|
[1] | 1612 | , public ISupportErrorInfo
|
---|
| 1613 | #else
|
---|
| 1614 | #endif
|
---|
| 1615 | {
|
---|
| 1616 | public:
|
---|
| 1617 |
|
---|
[6935] | 1618 | #if !defined (VBOX_WITH_XPCOM)
|
---|
[1] | 1619 | STDMETHOD(InterfaceSupportsErrorInfo) (REFIID riid)
|
---|
| 1620 | {
|
---|
| 1621 | const _ATL_INTMAP_ENTRY* pEntries = C::_GetEntries();
|
---|
| 1622 | Assert (pEntries);
|
---|
| 1623 | if (!pEntries)
|
---|
| 1624 | return S_FALSE;
|
---|
| 1625 |
|
---|
| 1626 | BOOL bSupports = FALSE;
|
---|
| 1627 | BOOL bISupportErrorInfoFound = FALSE;
|
---|
| 1628 |
|
---|
| 1629 | while (pEntries->pFunc != NULL && !bSupports)
|
---|
| 1630 | {
|
---|
| 1631 | if (!bISupportErrorInfoFound)
|
---|
| 1632 | {
|
---|
| 1633 | // skip the com map entries until ISupportErrorInfo is found
|
---|
| 1634 | bISupportErrorInfoFound =
|
---|
| 1635 | InlineIsEqualGUID (*(pEntries->piid), IID_ISupportErrorInfo);
|
---|
| 1636 | }
|
---|
| 1637 | else
|
---|
| 1638 | {
|
---|
| 1639 | // look for the requested interface in the rest of the com map
|
---|
| 1640 | bSupports = InlineIsEqualGUID (*(pEntries->piid), riid);
|
---|
| 1641 | }
|
---|
| 1642 | pEntries++;
|
---|
| 1643 | }
|
---|
| 1644 |
|
---|
| 1645 | Assert (bISupportErrorInfoFound);
|
---|
| 1646 |
|
---|
| 1647 | return bSupports ? S_OK : S_FALSE;
|
---|
| 1648 | }
|
---|
[6935] | 1649 | #endif // !defined (VBOX_WITH_XPCOM)
|
---|
[1] | 1650 |
|
---|
| 1651 | protected:
|
---|
| 1652 |
|
---|
| 1653 | /**
|
---|
| 1654 | * Sets the error information for the current thread.
|
---|
| 1655 | * This information can be retrieved by a caller of an interface method
|
---|
| 1656 | * using IErrorInfo on Windows or nsIException on Linux, or the cross-platform
|
---|
| 1657 | * IVirtualBoxErrorInfo interface that provides extended error info (only
|
---|
| 1658 | * for components from the VirtualBox COM library). Alternatively, the
|
---|
| 1659 | * platform-independent class com::ErrorInfo (defined in VBox[XP]COM.lib)
|
---|
| 1660 | * can be used to retrieve error info in a convenient way.
|
---|
| 1661 | *
|
---|
| 1662 | * It is assumed that the interface method that uses this function returns
|
---|
| 1663 | * an unsuccessful result code to the caller (otherwise, there is no reason
|
---|
| 1664 | * for the caller to try to retrieve error info after method invocation).
|
---|
| 1665 | *
|
---|
| 1666 | * Here is a table of correspondence between this method's arguments
|
---|
| 1667 | * and IErrorInfo/nsIException/IVirtualBoxErrorInfo attributes/methods:
|
---|
| 1668 | *
|
---|
| 1669 | * argument IErrorInfo nsIException IVirtualBoxErrorInfo
|
---|
| 1670 | * ----------------------------------------------------------------
|
---|
| 1671 | * resultCode -- result resultCode
|
---|
| 1672 | * iid GetGUID -- interfaceID
|
---|
| 1673 | * component GetSource -- component
|
---|
| 1674 | * text GetDescription message text
|
---|
| 1675 | *
|
---|
| 1676 | * This method is rarely needs to be used though. There are more convenient
|
---|
| 1677 | * overloaded versions, that automatically substitute some arguments
|
---|
| 1678 | * taking their values from the template parameters. See
|
---|
| 1679 | * #setError (HRESULT, const char *, ...) for an example.
|
---|
| 1680 | *
|
---|
[2672] | 1681 | * @param aResultCode result (error) code, must not be S_OK
|
---|
[14624] | 1682 | * @param aIID IID of the interface that defines the error
|
---|
[2672] | 1683 | * @param aComponent name of the component that generates the error
|
---|
| 1684 | * @param aText error message (must not be null), an RTStrPrintf-like
|
---|
[1] | 1685 | * format string in UTF-8 encoding
|
---|
| 1686 | * @param ... list of arguments for the format string
|
---|
| 1687 | *
|
---|
| 1688 | * @return
|
---|
[14624] | 1689 | * the error argument, for convenience, If an error occurs while
|
---|
[1] | 1690 | * creating error info itself, that error is returned instead of the
|
---|
| 1691 | * error argument.
|
---|
| 1692 | */
|
---|
[6935] | 1693 | static HRESULT setError (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1694 | const wchar_t *aComponent,
|
---|
| 1695 | const char *aText, ...)
|
---|
[1] | 1696 | {
|
---|
| 1697 | va_list args;
|
---|
[2672] | 1698 | va_start (args, aText);
|
---|
| 1699 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError
|
---|
[8709] | 1700 | (aResultCode, aIID, aComponent, aText, args, true /* aLogIt */);
|
---|
[1] | 1701 | va_end (args);
|
---|
| 1702 | return rc;
|
---|
| 1703 | }
|
---|
| 1704 |
|
---|
| 1705 | /**
|
---|
[6964] | 1706 | * This method is the same as #setError() except that it makes sure @a
|
---|
[14624] | 1707 | * aResultCode doesn't have the error severity bit (31) set when passed
|
---|
[6964] | 1708 | * down to the created IVirtualBoxErrorInfo object.
|
---|
| 1709 | *
|
---|
[14624] | 1710 | * The error severity bit is always cleared by this call, thereof you can
|
---|
| 1711 | * use ordinary E_XXX result code constants, for convenience. However, this
|
---|
| 1712 | * behavior may be non-standard on some COM platforms.
|
---|
[2672] | 1713 | */
|
---|
[6964] | 1714 | static HRESULT setWarning (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1715 | const wchar_t *aComponent,
|
---|
| 1716 | const char *aText, ...)
|
---|
[2672] | 1717 | {
|
---|
| 1718 | va_list args;
|
---|
| 1719 | va_start (args, aText);
|
---|
[6964] | 1720 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning
|
---|
[2672] | 1721 | (aResultCode, aIID, aComponent, aText, args);
|
---|
| 1722 | va_end (args);
|
---|
| 1723 | return rc;
|
---|
| 1724 | }
|
---|
| 1725 |
|
---|
| 1726 | /**
|
---|
[1] | 1727 | * Sets the error information for the current thread.
|
---|
| 1728 | * A convenience method that automatically sets the default interface
|
---|
| 1729 | * ID (taken from the I template argument) and the component name
|
---|
| 1730 | * (a value of C::getComponentName()).
|
---|
| 1731 | *
|
---|
| 1732 | * See #setError (HRESULT, const GUID &, const wchar_t *, const char *text, ...)
|
---|
| 1733 | * for details.
|
---|
| 1734 | *
|
---|
| 1735 | * This method is the most common (and convenient) way to set error
|
---|
| 1736 | * information from within interface methods. A typical pattern of usage
|
---|
| 1737 | * is looks like this:
|
---|
| 1738 | *
|
---|
| 1739 | * <code>
|
---|
| 1740 | * return setError (E_FAIL, "Terrible Error");
|
---|
| 1741 | * </code>
|
---|
| 1742 | * or
|
---|
| 1743 | * <code>
|
---|
| 1744 | * HRESULT rc = setError (E_FAIL, "Terrible Error");
|
---|
| 1745 | * ...
|
---|
| 1746 | * return rc;
|
---|
| 1747 | * </code>
|
---|
| 1748 | */
|
---|
[6935] | 1749 | static HRESULT setError (HRESULT aResultCode, const char *aText, ...)
|
---|
[1] | 1750 | {
|
---|
| 1751 | va_list args;
|
---|
[2672] | 1752 | va_start (args, aText);
|
---|
| 1753 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError
|
---|
[8709] | 1754 | (aResultCode, COM_IIDOF(I), C::getComponentName(), aText, args, true /* aLogIt */);
|
---|
[1] | 1755 | va_end (args);
|
---|
| 1756 | return rc;
|
---|
| 1757 | }
|
---|
| 1758 |
|
---|
| 1759 | /**
|
---|
[6964] | 1760 | * This method is the same as #setError() except that it makes sure @a
|
---|
[14624] | 1761 | * aResultCode doesn't have the error severity bit (31) set when passed
|
---|
[6964] | 1762 | * down to the created IVirtualBoxErrorInfo object.
|
---|
| 1763 | *
|
---|
[14624] | 1764 | * The error severity bit is always cleared by this call, thereof you can
|
---|
| 1765 | * use ordinary E_XXX result code constants, for convenience. However, this
|
---|
| 1766 | * behavior may be non-standard on some COM platforms.
|
---|
[2672] | 1767 | */
|
---|
[6964] | 1768 | static HRESULT setWarning (HRESULT aResultCode, const char *aText, ...)
|
---|
[2672] | 1769 | {
|
---|
| 1770 | va_list args;
|
---|
| 1771 | va_start (args, aText);
|
---|
[6964] | 1772 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning
|
---|
[2672] | 1773 | (aResultCode, COM_IIDOF(I), C::getComponentName(), aText, args);
|
---|
| 1774 | va_end (args);
|
---|
| 1775 | return rc;
|
---|
| 1776 | }
|
---|
| 1777 |
|
---|
| 1778 | /**
|
---|
[1] | 1779 | * Sets the error information for the current thread, va_list variant.
|
---|
| 1780 | * A convenience method that automatically sets the default interface
|
---|
| 1781 | * ID (taken from the I template argument) and the component name
|
---|
| 1782 | * (a value of C::getComponentName()).
|
---|
| 1783 | *
|
---|
| 1784 | * See #setError (HRESULT, const GUID &, const wchar_t *, const char *text, ...)
|
---|
[357] | 1785 | * and #setError (HRESULT, const char *, ...) for details.
|
---|
[1] | 1786 | */
|
---|
[6935] | 1787 | static HRESULT setErrorV (HRESULT aResultCode, const char *aText,
|
---|
| 1788 | va_list aArgs)
|
---|
[1] | 1789 | {
|
---|
[2672] | 1790 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError
|
---|
[8709] | 1791 | (aResultCode, COM_IIDOF(I), C::getComponentName(), aText, aArgs, true /* aLogIt */);
|
---|
[1] | 1792 | return rc;
|
---|
| 1793 | }
|
---|
| 1794 |
|
---|
| 1795 | /**
|
---|
[6964] | 1796 | * This method is the same as #setErrorV() except that it makes sure @a
|
---|
[14624] | 1797 | * aResultCode doesn't have the error severity bit (31) set when passed
|
---|
[6964] | 1798 | * down to the created IVirtualBoxErrorInfo object.
|
---|
| 1799 | *
|
---|
[14624] | 1800 | * The error severity bit is always cleared by this call, thereof you can
|
---|
| 1801 | * use ordinary E_XXX result code constants, for convenience. However, this
|
---|
| 1802 | * behavior may be non-standard on some COM platforms.
|
---|
[2672] | 1803 | */
|
---|
[6964] | 1804 | static HRESULT setWarningV (HRESULT aResultCode, const char *aText,
|
---|
| 1805 | va_list aArgs)
|
---|
[2672] | 1806 | {
|
---|
[6964] | 1807 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning
|
---|
[2672] | 1808 | (aResultCode, COM_IIDOF(I), C::getComponentName(), aText, aArgs);
|
---|
| 1809 | return rc;
|
---|
| 1810 | }
|
---|
| 1811 |
|
---|
| 1812 | /**
|
---|
[357] | 1813 | * Sets the error information for the current thread, BStr variant.
|
---|
| 1814 | * A convenience method that automatically sets the default interface
|
---|
| 1815 | * ID (taken from the I template argument) and the component name
|
---|
| 1816 | * (a value of C::getComponentName()).
|
---|
| 1817 | *
|
---|
[14624] | 1818 | * This method is preferred if you have a ready (translated and formatted)
|
---|
[6935] | 1819 | * Bstr string, because it omits an extra conversion Utf8Str -> Bstr.
|
---|
[357] | 1820 | *
|
---|
| 1821 | * See #setError (HRESULT, const GUID &, const wchar_t *, const char *text, ...)
|
---|
| 1822 | * and #setError (HRESULT, const char *, ...) for details.
|
---|
| 1823 | */
|
---|
[6935] | 1824 | static HRESULT setErrorBstr (HRESULT aResultCode, const Bstr &aText)
|
---|
[357] | 1825 | {
|
---|
[2672] | 1826 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError
|
---|
[8709] | 1827 | (aResultCode, COM_IIDOF(I), C::getComponentName(), aText, true /* aLogIt */);
|
---|
[357] | 1828 | return rc;
|
---|
| 1829 | }
|
---|
| 1830 |
|
---|
| 1831 | /**
|
---|
[6964] | 1832 | * This method is the same as #setErrorBstr() except that it makes sure @a
|
---|
[14624] | 1833 | * aResultCode doesn't have the error severity bit (31) set when passed
|
---|
[6964] | 1834 | * down to the created IVirtualBoxErrorInfo object.
|
---|
| 1835 | *
|
---|
[14624] | 1836 | * The error severity bit is always cleared by this call, thereof you can
|
---|
| 1837 | * use ordinary E_XXX result code constants, for convenience. However, this
|
---|
| 1838 | * behavior may be non-standard on some COM platforms.
|
---|
[2672] | 1839 | */
|
---|
[6964] | 1840 | static HRESULT setWarningBstr (HRESULT aResultCode, const Bstr &aText)
|
---|
[2672] | 1841 | {
|
---|
[6964] | 1842 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning
|
---|
[2672] | 1843 | (aResultCode, COM_IIDOF(I), C::getComponentName(), aText);
|
---|
| 1844 | return rc;
|
---|
| 1845 | }
|
---|
| 1846 |
|
---|
| 1847 | /**
|
---|
[1] | 1848 | * Sets the error information for the current thread.
|
---|
| 1849 | * A convenience method that automatically sets the component name
|
---|
| 1850 | * (a value of C::getComponentName()), but allows to specify the interface
|
---|
| 1851 | * id manually.
|
---|
| 1852 | *
|
---|
| 1853 | * See #setError (HRESULT, const GUID &, const wchar_t *, const char *text, ...)
|
---|
| 1854 | * for details.
|
---|
| 1855 | */
|
---|
[6935] | 1856 | static HRESULT setError (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1857 | const char *aText, ...)
|
---|
[1] | 1858 | {
|
---|
| 1859 | va_list args;
|
---|
[2672] | 1860 | va_start (args, aText);
|
---|
| 1861 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError
|
---|
[8709] | 1862 | (aResultCode, aIID, C::getComponentName(), aText, args, true /* aLogIt */);
|
---|
[1] | 1863 | va_end (args);
|
---|
| 1864 | return rc;
|
---|
| 1865 | }
|
---|
| 1866 |
|
---|
| 1867 | /**
|
---|
[6964] | 1868 | * This method is the same as #setError() except that it makes sure @a
|
---|
[14624] | 1869 | * aResultCode doesn't have the error severity bit (31) set when passed
|
---|
[6964] | 1870 | * down to the created IVirtualBoxErrorInfo object.
|
---|
| 1871 | *
|
---|
[14624] | 1872 | * The error severity bit is always cleared by this call, thereof you can
|
---|
| 1873 | * use ordinary E_XXX result code constants, for convenience. However, this
|
---|
| 1874 | * behavior may be non-standard on some COM platforms.
|
---|
[1] | 1875 | */
|
---|
[6964] | 1876 | static HRESULT setWarning (HRESULT aResultCode, const GUID &aIID,
|
---|
| 1877 | const char *aText, ...)
|
---|
[1] | 1878 | {
|
---|
[2672] | 1879 | va_list args;
|
---|
| 1880 | va_start (args, aText);
|
---|
[6964] | 1881 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning
|
---|
[2672] | 1882 | (aResultCode, aIID, C::getComponentName(), aText, args);
|
---|
| 1883 | va_end (args);
|
---|
| 1884 | return rc;
|
---|
[1] | 1885 | }
|
---|
| 1886 |
|
---|
[8709] | 1887 | /**
|
---|
| 1888 | * Sets the error information for the current thread but doesn't put
|
---|
| 1889 | * anything in the release log. This is very useful for avoiding
|
---|
| 1890 | * harmless error from causing confusion.
|
---|
| 1891 | *
|
---|
| 1892 | * It is otherwise identical to #setError (HRESULT, const char *text, ...).
|
---|
| 1893 | */
|
---|
| 1894 | static HRESULT setErrorNoLog (HRESULT aResultCode, const char *aText, ...)
|
---|
| 1895 | {
|
---|
| 1896 | va_list args;
|
---|
| 1897 | va_start (args, aText);
|
---|
| 1898 | HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError
|
---|
| 1899 | (aResultCode, COM_IIDOF(I), C::getComponentName(), aText, args, false /* aLogIt */);
|
---|
| 1900 | va_end (args);
|
---|
| 1901 | return rc;
|
---|
| 1902 | }
|
---|
| 1903 |
|
---|
[1] | 1904 | private:
|
---|
| 1905 |
|
---|
| 1906 | };
|
---|
| 1907 |
|
---|
| 1908 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 1909 |
|
---|
| 1910 | /**
|
---|
[14624] | 1911 | * Base class to track VirtualBoxBase children of the component.
|
---|
[1] | 1912 | *
|
---|
[14624] | 1913 | * This class is a preferable VirtualBoxBase replacement for components
|
---|
[1] | 1914 | * that operate with collections of child components. It gives two useful
|
---|
| 1915 | * possibilities:
|
---|
| 1916 | *
|
---|
| 1917 | * <ol><li>
|
---|
| 1918 | * Given an IUnknown instance, it's possible to quickly determine
|
---|
| 1919 | * whether this instance represents a child object created by the given
|
---|
| 1920 | * component, and if so, get a valid VirtualBoxBase pointer to the child
|
---|
| 1921 | * object. The returned pointer can be then safely casted to the
|
---|
| 1922 | * actual class of the child object (to get access to its "internal"
|
---|
| 1923 | * non-interface methods) provided that no other child components implement
|
---|
| 1924 | * the same initial interface IUnknown is queried from.
|
---|
| 1925 | * </li><li>
|
---|
| 1926 | * When the parent object uninitializes itself, it can easily unintialize
|
---|
| 1927 | * all its VirtualBoxBase derived children (using their
|
---|
| 1928 | * VirtualBoxBase::uninit() implementations). This is done simply by
|
---|
| 1929 | * calling the #uninitDependentChildren() method.
|
---|
[6851] | 1930 | * </li></ol>
|
---|
[1] | 1931 | *
|
---|
| 1932 | * In order to let the above work, the following must be done:
|
---|
| 1933 | * <ol><li>
|
---|
| 1934 | * When a child object is initialized, it calls #addDependentChild() of
|
---|
| 1935 | * its parent to register itself within the list of dependent children.
|
---|
| 1936 | * </li><li>
|
---|
| 1937 | * When a child object it is uninitialized, it calls #removeDependentChild()
|
---|
| 1938 | * to unregister itself. This must be done <b>after</b> the child has called
|
---|
| 1939 | * setReady(false) to indicate it is no more valid, and <b>not</b> from under
|
---|
| 1940 | * the child object's lock. Note also, that the first action the child's
|
---|
| 1941 | * uninit() implementation must do is to check for readiness after acquiring
|
---|
| 1942 | * the object's lock and return immediately if not ready.
|
---|
[6851] | 1943 | * </li></ol>
|
---|
[1] | 1944 | *
|
---|
| 1945 | * Children added by #addDependentChild() are <b>weakly</b> referenced
|
---|
| 1946 | * (i.e. AddRef() is not called), so when a child is externally destructed
|
---|
| 1947 | * (i.e. its reference count goes to zero), it will automatically remove
|
---|
| 1948 | * itself from a map of dependent children, provided that it follows the
|
---|
| 1949 | * rules described here.
|
---|
| 1950 | *
|
---|
| 1951 | * @note
|
---|
| 1952 | * Because of weak referencing, deadlocks and assertions are very likely
|
---|
| 1953 | * if #addDependentChild() or #removeDependentChild() are used incorrectly
|
---|
| 1954 | * (called at inappropriate times). Check the above rules once more.
|
---|
[6935] | 1955 | *
|
---|
[6851] | 1956 | * @deprecated Use VirtualBoxBaseWithChildrenNEXT for new classes.
|
---|
[1] | 1957 | */
|
---|
| 1958 | class VirtualBoxBaseWithChildren : public VirtualBoxBase
|
---|
| 1959 | {
|
---|
| 1960 | public:
|
---|
| 1961 |
|
---|
| 1962 | VirtualBoxBaseWithChildren()
|
---|
| 1963 | : mUninitDoneSem (NIL_RTSEMEVENT), mChildrenLeft (0)
|
---|
[7992] | 1964 | {}
|
---|
[1] | 1965 |
|
---|
| 1966 | virtual ~VirtualBoxBaseWithChildren()
|
---|
[7992] | 1967 | {}
|
---|
[1] | 1968 |
|
---|
| 1969 | /**
|
---|
| 1970 | * Adds the given child to the map of dependent children.
|
---|
| 1971 | * Intended to be called from the child's init() method,
|
---|
| 1972 | * from under the child's lock.
|
---|
| 1973 | *
|
---|
| 1974 | * @param C the child object to add (must inherit VirtualBoxBase AND
|
---|
| 1975 | * implement some interface)
|
---|
| 1976 | */
|
---|
| 1977 | template <class C>
|
---|
| 1978 | void addDependentChild (C *child)
|
---|
| 1979 | {
|
---|
| 1980 | AssertReturn (child, (void) 0);
|
---|
| 1981 | addDependentChild (child, child);
|
---|
| 1982 | }
|
---|
| 1983 |
|
---|
| 1984 | /**
|
---|
| 1985 | * Removes the given child from the map of dependent children.
|
---|
| 1986 | * Must be called <b>after<b> the child has called setReady(false), and
|
---|
| 1987 | * <b>not</b> from under the child object's lock.
|
---|
| 1988 | *
|
---|
| 1989 | * @param C the child object to remove (must inherit VirtualBoxBase AND
|
---|
| 1990 | * implement some interface)
|
---|
| 1991 | */
|
---|
| 1992 | template <class C>
|
---|
| 1993 | void removeDependentChild (C *child)
|
---|
| 1994 | {
|
---|
| 1995 | AssertReturn (child, (void) 0);
|
---|
| 1996 | /// @todo (r=dmik) the below check (and the relevant comment above)
|
---|
| 1997 | // seems to be not necessary any more once we completely switch to
|
---|
| 1998 | // the NEXT locking scheme. This requires altering removeDependentChild()
|
---|
| 1999 | // and uninitDependentChildren() as well (due to the new state scheme,
|
---|
| 2000 | // there is a separate mutex for state transition, so calling the
|
---|
| 2001 | // child's uninit() from under the children map lock should not produce
|
---|
| 2002 | // dead-locks any more).
|
---|
[8744] | 2003 | Assert (!child->isWriteLockOnCurrentThread() || child->lockHandle() == lockHandle());
|
---|
[1] | 2004 | removeDependentChild (ComPtr <IUnknown> (child));
|
---|
| 2005 | }
|
---|
| 2006 |
|
---|
| 2007 | protected:
|
---|
| 2008 |
|
---|
| 2009 | void uninitDependentChildren();
|
---|
| 2010 |
|
---|
| 2011 | VirtualBoxBase *getDependentChild (const ComPtr <IUnknown> &unk);
|
---|
| 2012 |
|
---|
| 2013 | private:
|
---|
| 2014 |
|
---|
| 2015 | void addDependentChild (const ComPtr <IUnknown> &unk, VirtualBoxBase *child);
|
---|
| 2016 | void removeDependentChild (const ComPtr <IUnknown> &unk);
|
---|
| 2017 |
|
---|
| 2018 | typedef std::map <IUnknown *, VirtualBoxBase *> DependentChildren;
|
---|
| 2019 | DependentChildren mDependentChildren;
|
---|
| 2020 |
|
---|
[7992] | 2021 | WriteLockHandle mMapLock;
|
---|
| 2022 |
|
---|
[1] | 2023 | RTSEMEVENT mUninitDoneSem;
|
---|
| 2024 | unsigned mChildrenLeft;
|
---|
| 2025 | };
|
---|
| 2026 |
|
---|
[6851] | 2027 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 2028 |
|
---|
[1] | 2029 | /**
|
---|
[6851] | 2030 | * Base class to track VirtualBoxBaseNEXT chlidren of the component.
|
---|
[1] | 2031 | *
|
---|
[6935] | 2032 | * This class is a preferrable VirtualBoxBase replacement for components that
|
---|
| 2033 | * operate with collections of child components. It gives two useful
|
---|
| 2034 | * possibilities:
|
---|
| 2035 | *
|
---|
| 2036 | * <ol><li>
|
---|
| 2037 | * Given an IUnknown instance, it's possible to quickly determine
|
---|
[13729] | 2038 | * whether this instance represents a child object that belongs to the
|
---|
| 2039 | * given component, and if so, get a valid VirtualBoxBase pointer to the
|
---|
| 2040 | * child object. The returned pointer can be then safely casted to the
|
---|
[6851] | 2041 | * actual class of the child object (to get access to its "internal"
|
---|
| 2042 | * non-interface methods) provided that no other child components implement
|
---|
[14624] | 2043 | * the same original COM interface IUnknown is queried from.
|
---|
[6851] | 2044 | * </li><li>
|
---|
| 2045 | * When the parent object uninitializes itself, it can easily unintialize
|
---|
| 2046 | * all its VirtualBoxBase derived children (using their
|
---|
| 2047 | * VirtualBoxBase::uninit() implementations). This is done simply by
|
---|
| 2048 | * calling the #uninitDependentChildren() method.
|
---|
| 2049 | * </li></ol>
|
---|
| 2050 | *
|
---|
| 2051 | * In order to let the above work, the following must be done:
|
---|
| 2052 | * <ol><li>
|
---|
| 2053 | * When a child object is initialized, it calls #addDependentChild() of
|
---|
| 2054 | * its parent to register itself within the list of dependent children.
|
---|
| 2055 | * </li><li>
|
---|
[13729] | 2056 | * When the child object it is uninitialized, it calls
|
---|
| 2057 | * #removeDependentChild() to unregister itself.
|
---|
[6851] | 2058 | * </li></ol>
|
---|
| 2059 | *
|
---|
[13729] | 2060 | * Note that if the parent object does not call #uninitDependentChildren() when
|
---|
| 2061 | * it gets uninitialized, it must call uninit() methods of individual children
|
---|
| 2062 | * manually to disconnect them; a failure to do so will cause crashes in these
|
---|
[14624] | 2063 | * methods when children get destroyed. The same applies to children not calling
|
---|
| 2064 | * #removeDependentChild() when getting destroyed.
|
---|
[13729] | 2065 | *
|
---|
[6851] | 2066 | * Note that children added by #addDependentChild() are <b>weakly</b> referenced
|
---|
[6935] | 2067 | * (i.e. AddRef() is not called), so when a child object is deleted externally
|
---|
| 2068 | * (because it's reference count goes to zero), it will automatically remove
|
---|
[6851] | 2069 | * itself from the map of dependent children provided that it follows the rules
|
---|
[6935] | 2070 | * described here.
|
---|
[6851] | 2071 | *
|
---|
[13729] | 2072 | * Access to the child list is serialized using the #childrenLock() lock handle
|
---|
| 2073 | * (which defaults to the general object lock handle (see
|
---|
| 2074 | * VirtualBoxBase::lockHandle()). This lock is used by all add/remove methods of
|
---|
| 2075 | * this class so be aware of the need to preserve the {parent, child} lock order
|
---|
| 2076 | * when calling these methods.
|
---|
[6935] | 2077 | *
|
---|
[13887] | 2078 | * Read individual method descriptions to get further information.
|
---|
| 2079 | *
|
---|
[6935] | 2080 | * @todo This is a VirtualBoxBaseWithChildren equivalent that uses the
|
---|
[14624] | 2081 | * VirtualBoxBaseNEXT implementation. Will completely supersede
|
---|
[6851] | 2082 | * VirtualBoxBaseWithChildren after the old VirtualBoxBase implementation
|
---|
| 2083 | * has gone.
|
---|
[1] | 2084 | */
|
---|
[6851] | 2085 | class VirtualBoxBaseWithChildrenNEXT : public VirtualBoxBaseNEXT
|
---|
[1] | 2086 | {
|
---|
[6851] | 2087 | public:
|
---|
| 2088 |
|
---|
| 2089 | VirtualBoxBaseWithChildrenNEXT()
|
---|
| 2090 | {}
|
---|
| 2091 |
|
---|
| 2092 | virtual ~VirtualBoxBaseWithChildrenNEXT()
|
---|
| 2093 | {}
|
---|
| 2094 |
|
---|
| 2095 | /**
|
---|
[13729] | 2096 | * Lock handle to use when adding/removing child objects from the list of
|
---|
| 2097 | * children. It is guaranteed that no any other lock is requested in methods
|
---|
| 2098 | * of this class while holding this lock.
|
---|
[6851] | 2099 | *
|
---|
[13729] | 2100 | * @warning By default, this simply returns the general object's lock handle
|
---|
| 2101 | * (see VirtualBoxBase::lockHandle()) which is sufficient for most
|
---|
| 2102 | * cases.
|
---|
| 2103 | */
|
---|
| 2104 | virtual RWLockHandle *childrenLock() { return lockHandle(); }
|
---|
| 2105 |
|
---|
| 2106 | /**
|
---|
| 2107 | * Adds the given child to the list of dependent children.
|
---|
[6851] | 2108 | *
|
---|
[13729] | 2109 | * Usually gets called from the child's init() method.
|
---|
| 2110 | *
|
---|
| 2111 | * @note @a aChild (unless it is in InInit state) must be protected by
|
---|
| 2112 | * VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
|
---|
| 2113 | * another thread during this method's call.
|
---|
| 2114 | *
|
---|
| 2115 | * @note When #childrenLock() is not overloaded (returns the general object
|
---|
| 2116 | * lock) and this method is called from under the child's read or
|
---|
| 2117 | * write lock, make sure the {parent, child} locking order is
|
---|
| 2118 | * preserved by locking the callee (this object) for writing before
|
---|
| 2119 | * the child's lock.
|
---|
| 2120 | *
|
---|
[6935] | 2121 | * @param aChild Child object to add (must inherit VirtualBoxBase AND
|
---|
[6851] | 2122 | * implement some interface).
|
---|
[13729] | 2123 | *
|
---|
| 2124 | * @note Locks #childrenLock() for writing.
|
---|
[6851] | 2125 | */
|
---|
| 2126 | template <class C>
|
---|
| 2127 | void addDependentChild (C *aChild)
|
---|
| 2128 | {
|
---|
[13729] | 2129 | AssertReturnVoid (aChild != NULL);
|
---|
[6851] | 2130 | doAddDependentChild (ComPtr <IUnknown> (aChild), aChild);
|
---|
| 2131 | }
|
---|
| 2132 |
|
---|
| 2133 | /**
|
---|
[13580] | 2134 | * Equivalent to template <class C> void addDependentChild (C *aChild)
|
---|
| 2135 | * but takes a ComObjPtr <C> argument.
|
---|
| 2136 | */
|
---|
| 2137 | template <class C>
|
---|
| 2138 | void addDependentChild (const ComObjPtr <C> &aChild)
|
---|
| 2139 | {
|
---|
| 2140 | AssertReturnVoid (!aChild.isNull());
|
---|
| 2141 | doAddDependentChild (ComPtr <IUnknown> (static_cast <C *> (aChild)), aChild);
|
---|
| 2142 | }
|
---|
| 2143 |
|
---|
| 2144 | /**
|
---|
[13729] | 2145 | * Removes the given child from the list of dependent children.
|
---|
[6851] | 2146 | *
|
---|
[13729] | 2147 | * Usually gets called from the child's uninit() method.
|
---|
[6935] | 2148 | *
|
---|
[13887] | 2149 | * Keep in mind that the called (parent) object may be no longer available
|
---|
| 2150 | * (i.e. may be deleted deleted) after this method returns, so you must not
|
---|
| 2151 | * call any other parent's methods after that!
|
---|
| 2152 | *
|
---|
[13729] | 2153 | * @note Locks #childrenLock() for writing.
|
---|
[6935] | 2154 | *
|
---|
[13729] | 2155 | * @note @a aChild (unless it is in InUninit state) must be protected by
|
---|
| 2156 | * VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
|
---|
| 2157 | * another thread during this method's call.
|
---|
| 2158 | *
|
---|
| 2159 | * @note When #childrenLock() is not overloaded (returns the general object
|
---|
| 2160 | * lock) and this method is called from under the child's read or
|
---|
| 2161 | * write lock, make sure the {parent, child} locking order is
|
---|
| 2162 | * preserved by locking the callee (this object) for writing before
|
---|
| 2163 | * the child's lock. This is irrelevant when the method is called from
|
---|
| 2164 | * under this object's VirtualBoxBaseProto::AutoUninitSpan (i.e. in
|
---|
| 2165 | * InUninit state) since in this case no locking is done.
|
---|
| 2166 | *
|
---|
| 2167 | * @param aChild Child object to remove.
|
---|
| 2168 | *
|
---|
| 2169 | * @note Locks #childrenLock() for writing.
|
---|
[6851] | 2170 | */
|
---|
| 2171 | template <class C>
|
---|
| 2172 | void removeDependentChild (C *aChild)
|
---|
| 2173 | {
|
---|
[13729] | 2174 | AssertReturnVoid (aChild != NULL);
|
---|
[6851] | 2175 | doRemoveDependentChild (ComPtr <IUnknown> (aChild));
|
---|
| 2176 | }
|
---|
| 2177 |
|
---|
[13580] | 2178 | /**
|
---|
| 2179 | * Equivalent to template <class C> void removeDependentChild (C *aChild)
|
---|
| 2180 | * but takes a ComObjPtr <C> argument.
|
---|
| 2181 | */
|
---|
| 2182 | template <class C>
|
---|
| 2183 | void removeDependentChild (const ComObjPtr <C> &aChild)
|
---|
| 2184 | {
|
---|
| 2185 | AssertReturnVoid (!aChild.isNull());
|
---|
| 2186 | doRemoveDependentChild (ComPtr <IUnknown> (static_cast <C *> (aChild)));
|
---|
| 2187 | }
|
---|
| 2188 |
|
---|
[6851] | 2189 | protected:
|
---|
| 2190 |
|
---|
| 2191 | void uninitDependentChildren();
|
---|
| 2192 |
|
---|
| 2193 | VirtualBoxBaseNEXT *getDependentChild (const ComPtr <IUnknown> &aUnk);
|
---|
| 2194 |
|
---|
[1] | 2195 | private:
|
---|
| 2196 |
|
---|
[6851] | 2197 | /// @todo temporarily reinterpret VirtualBoxBase * as VirtualBoxBaseNEXT *
|
---|
| 2198 | // until ported HardDisk and Progress to the new scheme.
|
---|
| 2199 | void doAddDependentChild (IUnknown *aUnk, VirtualBoxBase *aChild)
|
---|
| 2200 | {
|
---|
| 2201 | doAddDependentChild (aUnk,
|
---|
| 2202 | reinterpret_cast <VirtualBoxBaseNEXT *> (aChild));
|
---|
| 2203 | }
|
---|
| 2204 |
|
---|
| 2205 | void doAddDependentChild (IUnknown *aUnk, VirtualBoxBaseNEXT *aChild);
|
---|
| 2206 | void doRemoveDependentChild (IUnknown *aUnk);
|
---|
| 2207 |
|
---|
| 2208 | typedef std::map <IUnknown *, VirtualBoxBaseNEXT *> DependentChildren;
|
---|
| 2209 | DependentChildren mDependentChildren;
|
---|
[1] | 2210 | };
|
---|
| 2211 |
|
---|
| 2212 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 2213 |
|
---|
| 2214 | /**
|
---|
[8637] | 2215 | * Base class to track component's children of some particular type.
|
---|
[1] | 2216 | *
|
---|
| 2217 | * This class is similar to VirtualBoxBaseWithChildren, with the exception
|
---|
| 2218 | * that all children must be of the same type. For this reason, it's not
|
---|
| 2219 | * necessary to use a map to store children, so a list is used instead.
|
---|
| 2220 | *
|
---|
| 2221 | * As opposed to VirtualBoxBaseWithChildren, children added by
|
---|
| 2222 | * #addDependentChild() are <b>strongly</b> referenced, so that they cannot
|
---|
| 2223 | * be externally destructed until #removeDependentChild() is called.
|
---|
| 2224 | *
|
---|
[13729] | 2225 | * Also, this class doesn't have the
|
---|
| 2226 | * VirtualBoxBaseWithChildrenNEXT::getDependentChild() method because it would
|
---|
| 2227 | * be not fast for long lists.
|
---|
| 2228 | *
|
---|
[1] | 2229 | * @param C type of child objects (must inherit VirtualBoxBase AND
|
---|
| 2230 | * implement some interface)
|
---|
[6935] | 2231 | *
|
---|
[6851] | 2232 | * @deprecated Use VirtualBoxBaseWithTypedChildrenNEXT for new classes.
|
---|
[1] | 2233 | */
|
---|
| 2234 | template <class C>
|
---|
| 2235 | class VirtualBoxBaseWithTypedChildren : public VirtualBoxBase
|
---|
| 2236 | {
|
---|
| 2237 | public:
|
---|
| 2238 |
|
---|
| 2239 | typedef std::list <ComObjPtr <C> > DependentChildren;
|
---|
| 2240 |
|
---|
| 2241 | VirtualBoxBaseWithTypedChildren() : mInUninit (false) {}
|
---|
| 2242 |
|
---|
| 2243 | virtual ~VirtualBoxBaseWithTypedChildren() {}
|
---|
| 2244 |
|
---|
| 2245 | /**
|
---|
| 2246 | * Adds the given child to the list of dependent children.
|
---|
| 2247 | * Must be called from the child's init() method,
|
---|
| 2248 | * from under the child's lock.
|
---|
| 2249 | *
|
---|
| 2250 | * @param C the child object to add (must inherit VirtualBoxBase AND
|
---|
| 2251 | * implement some interface)
|
---|
| 2252 | */
|
---|
| 2253 | void addDependentChild (C *child)
|
---|
| 2254 | {
|
---|
| 2255 | AssertReturn (child, (void) 0);
|
---|
| 2256 |
|
---|
[8083] | 2257 | AutoWriteLock alock (mMapLock);
|
---|
[1] | 2258 | if (mInUninit)
|
---|
| 2259 | return;
|
---|
| 2260 |
|
---|
| 2261 | mDependentChildren.push_back (child);
|
---|
| 2262 | }
|
---|
| 2263 |
|
---|
| 2264 | /**
|
---|
| 2265 | * Removes the given child from the list of dependent children.
|
---|
| 2266 | * Must be called from the child's uninit() method,
|
---|
| 2267 | * under the child's lock.
|
---|
| 2268 | *
|
---|
| 2269 | * @param C the child object to remove (must inherit VirtualBoxBase AND
|
---|
| 2270 | * implement some interface)
|
---|
| 2271 | */
|
---|
| 2272 | void removeDependentChild (C *child)
|
---|
| 2273 | {
|
---|
| 2274 | AssertReturn (child, (void) 0);
|
---|
| 2275 |
|
---|
[8083] | 2276 | AutoWriteLock alock (mMapLock);
|
---|
[1] | 2277 | if (mInUninit)
|
---|
| 2278 | return;
|
---|
| 2279 |
|
---|
| 2280 | mDependentChildren.remove (child);
|
---|
| 2281 | }
|
---|
| 2282 |
|
---|
| 2283 | protected:
|
---|
| 2284 |
|
---|
| 2285 | /**
|
---|
| 2286 | * Returns an internal lock handle to lock the list of children
|
---|
[13580] | 2287 | * returned by #dependentChildren() using AutoReadLock/AutoWriteLock:
|
---|
[1] | 2288 | * <code>
|
---|
[13580] | 2289 | * AutoReadLock alock (dependentChildrenLock());
|
---|
[1] | 2290 | * </code>
|
---|
[13580] | 2291 | *
|
---|
| 2292 | * This is necessary for example to access the list of children returned by
|
---|
| 2293 | * #dependentChildren().
|
---|
[1] | 2294 | */
|
---|
[7992] | 2295 | RWLockHandle *dependentChildrenLock() const { return &mMapLock; }
|
---|
[1] | 2296 |
|
---|
| 2297 | /**
|
---|
| 2298 | * Returns the read-only list of all dependent children.
|
---|
| 2299 | * @note
|
---|
| 2300 | * Access the returned list (iterate, get size etc.) only after
|
---|
[8083] | 2301 | * doing |AutoWriteLock alock (dependentChildrenLock());|!
|
---|
[1] | 2302 | */
|
---|
| 2303 | const DependentChildren &dependentChildren() const { return mDependentChildren; }
|
---|
| 2304 |
|
---|
| 2305 | /**
|
---|
| 2306 | * Uninitializes all dependent children registered with #addDependentChild().
|
---|
| 2307 | *
|
---|
| 2308 | * @note
|
---|
| 2309 | * This method will call uninit() methods of children. If these methods
|
---|
| 2310 | * access the parent object, uninitDependentChildren() must be called
|
---|
| 2311 | * either at the beginning of the parent uninitialization sequence (when
|
---|
| 2312 | * it is still operational) or after setReady(false) is called to
|
---|
| 2313 | * indicate the parent is out of action.
|
---|
| 2314 | */
|
---|
| 2315 | void uninitDependentChildren()
|
---|
| 2316 | {
|
---|
[8083] | 2317 | AutoWriteLock alock (this);
|
---|
| 2318 | AutoWriteLock mapLock (mMapLock);
|
---|
[1] | 2319 |
|
---|
| 2320 | if (mDependentChildren.size())
|
---|
| 2321 | {
|
---|
| 2322 | // set flag to ignore #removeDependentChild() called from child->uninit()
|
---|
| 2323 | mInUninit = true;
|
---|
| 2324 |
|
---|
| 2325 | // leave the locks to let children waiting for #removeDependentChild() run
|
---|
| 2326 | mapLock.leave();
|
---|
| 2327 | alock.leave();
|
---|
| 2328 |
|
---|
| 2329 | for (typename DependentChildren::iterator it = mDependentChildren.begin();
|
---|
| 2330 | it != mDependentChildren.end(); ++ it)
|
---|
| 2331 | {
|
---|
| 2332 | C *child = (*it);
|
---|
| 2333 | Assert (child);
|
---|
| 2334 | if (child)
|
---|
| 2335 | child->uninit();
|
---|
| 2336 | }
|
---|
| 2337 | mDependentChildren.clear();
|
---|
| 2338 |
|
---|
| 2339 | alock.enter();
|
---|
| 2340 | mapLock.enter();
|
---|
| 2341 |
|
---|
| 2342 | mInUninit = false;
|
---|
| 2343 | }
|
---|
| 2344 | }
|
---|
| 2345 |
|
---|
| 2346 | /**
|
---|
| 2347 | * Removes (detaches) all dependent children registered with
|
---|
| 2348 | * #addDependentChild(), without uninitializing them.
|
---|
| 2349 | *
|
---|
| 2350 | * @note This method must be called from under the main object's lock
|
---|
| 2351 | */
|
---|
| 2352 | void removeDependentChildren()
|
---|
| 2353 | {
|
---|
[8083] | 2354 | AutoWriteLock alock (mMapLock);
|
---|
[1] | 2355 | mDependentChildren.clear();
|
---|
| 2356 | }
|
---|
| 2357 |
|
---|
| 2358 | private:
|
---|
| 2359 |
|
---|
| 2360 | DependentChildren mDependentChildren;
|
---|
| 2361 |
|
---|
| 2362 | bool mInUninit;
|
---|
[7992] | 2363 | mutable RWLockHandle mMapLock;
|
---|
[1] | 2364 | };
|
---|
| 2365 |
|
---|
[6851] | 2366 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 2367 |
|
---|
[1] | 2368 | /**
|
---|
[14624] | 2369 | * Base class to track component's children of the particular type.
|
---|
[1] | 2370 | *
|
---|
[13729] | 2371 | * This class is similar to VirtualBoxBaseWithChildrenNEXT with the exception
|
---|
| 2372 | * that all children must be of the same type. For this reason, it's not
|
---|
| 2373 | * necessary to use a map to store children -- a list is used instead.
|
---|
[6851] | 2374 | *
|
---|
[13580] | 2375 | * Also, as opposed to VirtualBoxBaseWithChildren, children added by
|
---|
[6935] | 2376 | * #addDependentChild() are <b>strongly</b> referenced, so that they cannot be
|
---|
[13887] | 2377 | * deleted (even by a third party) until #removeDependentChild() is called on
|
---|
| 2378 | * them. This also means that a failure to call #removeDependentChild() and
|
---|
| 2379 | * #uninitDependentChildren() at appropriate times as described in
|
---|
| 2380 | * VirtualBoxBaseWithChildrenNEXT may cause stuck references that won't be able
|
---|
| 2381 | * uninitialize themselves.
|
---|
[6851] | 2382 | *
|
---|
[13887] | 2383 | * See individual method descriptions for further information.
|
---|
[13580] | 2384 | *
|
---|
[13729] | 2385 | * @param C Type of child objects (must inherit VirtualBoxBase AND implement
|
---|
| 2386 | * some interface).
|
---|
[6935] | 2387 | *
|
---|
| 2388 | * @todo This is a VirtualBoxBaseWithChildren equivalent that uses the
|
---|
[14624] | 2389 | * VirtualBoxBaseNEXT implementation. Will completely supersede
|
---|
[6851] | 2390 | * VirtualBoxBaseWithChildren after the old VirtualBoxBase implementation
|
---|
| 2391 | * has gone.
|
---|
[1] | 2392 | */
|
---|
| 2393 | template <class C>
|
---|
[6851] | 2394 | class VirtualBoxBaseWithTypedChildrenNEXT : public VirtualBoxBaseNEXT
|
---|
[1] | 2395 | {
|
---|
| 2396 | public:
|
---|
| 2397 |
|
---|
[6851] | 2398 | typedef std::list <ComObjPtr <C> > DependentChildren;
|
---|
[1] | 2399 |
|
---|
[13580] | 2400 | VirtualBoxBaseWithTypedChildrenNEXT() {}
|
---|
[6851] | 2401 |
|
---|
| 2402 | virtual ~VirtualBoxBaseWithTypedChildrenNEXT() {}
|
---|
| 2403 |
|
---|
| 2404 | /**
|
---|
[13729] | 2405 | * Lock handle to use when adding/removing child objects from the list of
|
---|
| 2406 | * children. It is guaranteed that no any other lock is requested in methods
|
---|
| 2407 | * of this class while holding this lock.
|
---|
| 2408 | *
|
---|
| 2409 | * @warning By default, this simply returns the general object's lock handle
|
---|
| 2410 | * (see VirtualBoxBase::lockHandle()) which is sufficient for most
|
---|
| 2411 | * cases.
|
---|
| 2412 | */
|
---|
| 2413 | virtual RWLockHandle *childrenLock() { return lockHandle(); }
|
---|
| 2414 |
|
---|
| 2415 | /**
|
---|
[6935] | 2416 | * Adds the given child to the list of dependent children.
|
---|
| 2417 | *
|
---|
[13580] | 2418 | * Usually gets called from the child's init() method.
|
---|
[6851] | 2419 | *
|
---|
[13580] | 2420 | * @note @a aChild (unless it is in InInit state) must be protected by
|
---|
| 2421 | * VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
|
---|
| 2422 | * another thread during this method's call.
|
---|
| 2423 | *
|
---|
[13729] | 2424 | * @note When #childrenLock() is not overloaded (returns the general object
|
---|
| 2425 | * lock) and this method is called from under the child's read or
|
---|
| 2426 | * write lock, make sure the {parent, child} locking order is
|
---|
| 2427 | * preserved by locking the callee (this object) for writing before
|
---|
| 2428 | * the child's lock.
|
---|
[13580] | 2429 | *
|
---|
| 2430 | * @param aChild Child object to add.
|
---|
[13729] | 2431 | *
|
---|
| 2432 | * @note Locks #childrenLock() for writing.
|
---|
[6851] | 2433 | */
|
---|
| 2434 | void addDependentChild (C *aChild)
|
---|
| 2435 | {
|
---|
[13729] | 2436 | AssertReturnVoid (aChild != NULL);
|
---|
[6851] | 2437 |
|
---|
[13580] | 2438 | AutoCaller autoCaller (this);
|
---|
[6851] | 2439 |
|
---|
[13580] | 2440 | /* sanity */
|
---|
| 2441 | AssertReturnVoid (autoCaller.state() == InInit ||
|
---|
| 2442 | autoCaller.state() == Ready ||
|
---|
| 2443 | autoCaller.state() == Limited);
|
---|
| 2444 |
|
---|
[13887] | 2445 | AutoWriteLock chLock (childrenLock());
|
---|
[6851] | 2446 | mDependentChildren.push_back (aChild);
|
---|
| 2447 | }
|
---|
| 2448 |
|
---|
| 2449 | /**
|
---|
[6935] | 2450 | * Removes the given child from the list of dependent children.
|
---|
[6851] | 2451 | *
|
---|
[13580] | 2452 | * Usually gets called from the child's uninit() method.
|
---|
[6935] | 2453 | *
|
---|
[13887] | 2454 | * Keep in mind that the called (parent) object may be no longer available
|
---|
| 2455 | * (i.e. may be deleted deleted) after this method returns, so you must not
|
---|
| 2456 | * call any other parent's methods after that!
|
---|
[13580] | 2457 | *
|
---|
| 2458 | * @note @a aChild (unless it is in InUninit state) must be protected by
|
---|
| 2459 | * VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
|
---|
| 2460 | * another thread during this method's call.
|
---|
| 2461 | *
|
---|
[13729] | 2462 | * @note When #childrenLock() is not overloaded (returns the general object
|
---|
| 2463 | * lock) and this method is called from under the child's read or
|
---|
| 2464 | * write lock, make sure the {parent, child} locking order is
|
---|
| 2465 | * preserved by locking the callee (this object) for writing before
|
---|
| 2466 | * the child's lock. This is irrelevant when the method is called from
|
---|
| 2467 | * under this object's AutoUninitSpan (i.e. in InUninit state) since
|
---|
| 2468 | * in this case no locking is done.
|
---|
[13580] | 2469 | *
|
---|
| 2470 | * @param aChild Child object to remove.
|
---|
[13729] | 2471 | *
|
---|
| 2472 | * @note Locks #childrenLock() for writing.
|
---|
[6851] | 2473 | */
|
---|
| 2474 | void removeDependentChild (C *aChild)
|
---|
| 2475 | {
|
---|
| 2476 | AssertReturnVoid (aChild);
|
---|
| 2477 |
|
---|
[13580] | 2478 | AutoCaller autoCaller (this);
|
---|
| 2479 |
|
---|
[13887] | 2480 | /* sanity */
|
---|
| 2481 | AssertReturnVoid (autoCaller.state() == InUninit ||
|
---|
| 2482 | autoCaller.state() == InInit ||
|
---|
| 2483 | autoCaller.state() == Ready ||
|
---|
| 2484 | autoCaller.state() == Limited);
|
---|
| 2485 |
|
---|
| 2486 | /* return shortly; we are strongly referenced so the object won't get
|
---|
| 2487 | * deleted if it calls init() before uninitDependentChildren() does
|
---|
| 2488 | * and therefore the list will still contain a valid reference that will
|
---|
| 2489 | * be correctly processed by uninitDependentChildren() anyway */
|
---|
[13580] | 2490 | if (autoCaller.state() == InUninit)
|
---|
[6851] | 2491 | return;
|
---|
| 2492 |
|
---|
[13887] | 2493 | AutoWriteLock chLock (childrenLock());
|
---|
[6851] | 2494 | mDependentChildren.remove (aChild);
|
---|
| 2495 | }
|
---|
| 2496 |
|
---|
| 2497 | protected:
|
---|
| 2498 |
|
---|
| 2499 | /**
|
---|
[13580] | 2500 | * Returns the read-only list of all dependent children.
|
---|
| 2501 | *
|
---|
[13729] | 2502 | * @note Access the returned list (iterate, get size etc.) only after making
|
---|
| 2503 | * sure #childrenLock() is locked for reading or for writing!
|
---|
[6851] | 2504 | */
|
---|
[13580] | 2505 | const DependentChildren &dependentChildren() const { return mDependentChildren; }
|
---|
[6851] | 2506 |
|
---|
| 2507 | /**
|
---|
[13580] | 2508 | * Uninitializes all dependent children registered on this object with
|
---|
| 2509 | * #addDependentChild().
|
---|
[6935] | 2510 | *
|
---|
[13580] | 2511 | * Must be called from within the VirtualBoxBaseProto::AutoUninitSpan (i.e.
|
---|
| 2512 | * typically from this object's uninit() method) to uninitialize children
|
---|
| 2513 | * before this object goes out of service and becomes unusable.
|
---|
| 2514 | *
|
---|
| 2515 | * Note that this method will call uninit() methods of child objects. If
|
---|
| 2516 | * these methods need to call the parent object during uninitialization,
|
---|
| 2517 | * #uninitDependentChildren() must be called before the relevant part of the
|
---|
[14624] | 2518 | * parent is uninitialized: usually at the beginning of the parent
|
---|
[13580] | 2519 | * uninitialization sequence.
|
---|
| 2520 | *
|
---|
[13729] | 2521 | * @note May lock something through the called children.
|
---|
[6851] | 2522 | */
|
---|
[13580] | 2523 | void uninitDependentChildren()
|
---|
| 2524 | {
|
---|
| 2525 | AutoCaller autoCaller (this);
|
---|
[6851] | 2526 |
|
---|
[13729] | 2527 | /* We don't want to hold the childrenLock() write lock here (necessary
|
---|
| 2528 | * to protect mDependentChildren) when uninitializing children because
|
---|
| 2529 | * we want to avoid a possible deadlock where we could get stuck in
|
---|
| 2530 | * child->uninit() blocked by AutoUninitSpan waiting for the number of
|
---|
[13887] | 2531 | * child's callers to drop to zero (or for another AutoUninitSpan to
|
---|
| 2532 | * finish), while some other thread is stuck in our
|
---|
| 2533 | * removeDependentChild() method called for that child and waiting for
|
---|
| 2534 | * the childrenLock()'s write lock.
|
---|
[13580] | 2535 | *
|
---|
| 2536 | * The only safe place to not lock and keep accessing our data members
|
---|
| 2537 | * is the InUninit state (no active call to our object may exist on
|
---|
| 2538 | * another thread when we are in InUinint, provided that all such calls
|
---|
| 2539 | * use the AutoCaller class of course). InUinint is also used as a flag
|
---|
| 2540 | * by removeDependentChild() that prevents touching mDependentChildren
|
---|
[13887] | 2541 | * from outside. Therefore, we assert. Note that InInit is also fine
|
---|
| 2542 | * since no any object may access us by that time.
|
---|
[13580] | 2543 | */
|
---|
[13887] | 2544 | AssertReturnVoid (autoCaller.state() == InUninit ||
|
---|
| 2545 | autoCaller.state() == InInit);
|
---|
[6851] | 2546 |
|
---|
[13580] | 2547 | if (mDependentChildren.size())
|
---|
| 2548 | {
|
---|
| 2549 | for (typename DependentChildren::iterator it = mDependentChildren.begin();
|
---|
| 2550 | it != mDependentChildren.end(); ++ it)
|
---|
| 2551 | {
|
---|
| 2552 | C *child = (*it);
|
---|
| 2553 | Assert (child);
|
---|
| 2554 |
|
---|
| 2555 | /* Note that if child->uninit() happens to be called on another
|
---|
[13729] | 2556 | * thread right before us and is not yet finished, the second
|
---|
[13580] | 2557 | * uninit() call will wait until the first one has done so
|
---|
| 2558 | * (thanks to AutoUninitSpan). */
|
---|
| 2559 | if (child)
|
---|
| 2560 | child->uninit();
|
---|
| 2561 | }
|
---|
| 2562 |
|
---|
| 2563 | /* release all strong references we hold */
|
---|
| 2564 | mDependentChildren.clear();
|
---|
| 2565 | }
|
---|
| 2566 | }
|
---|
| 2567 |
|
---|
[6851] | 2568 | /**
|
---|
| 2569 | * Removes (detaches) all dependent children registered with
|
---|
| 2570 | * #addDependentChild(), without uninitializing them.
|
---|
| 2571 | *
|
---|
[13580] | 2572 | * @note @a |this| (unless it is in InUninit state) must be protected by
|
---|
| 2573 | * VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
|
---|
| 2574 | * another thread during this method's call.
|
---|
| 2575 | *
|
---|
[13729] | 2576 | * @note Locks #childrenLock() for writing.
|
---|
[6851] | 2577 | */
|
---|
| 2578 | void removeDependentChildren()
|
---|
| 2579 | {
|
---|
[13887] | 2580 | AutoWriteLock chLock (childrenLock());
|
---|
[6851] | 2581 | mDependentChildren.clear();
|
---|
| 2582 | }
|
---|
| 2583 |
|
---|
[1] | 2584 | private:
|
---|
| 2585 |
|
---|
[6851] | 2586 | DependentChildren mDependentChildren;
|
---|
[1] | 2587 | };
|
---|
| 2588 |
|
---|
| 2589 | ////////////////////////////////////////////////////////////////////////////////
|
---|
| 2590 |
|
---|
| 2591 | /// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
|
---|
| 2592 | /**
|
---|
| 2593 | * Simple template that manages data structure allocation/deallocation
|
---|
| 2594 | * and supports data pointer sharing (the instance that shares the pointer is
|
---|
| 2595 | * not responsible for memory deallocation as opposed to the instance that
|
---|
| 2596 | * owns it).
|
---|
| 2597 | */
|
---|
| 2598 | template <class D>
|
---|
| 2599 | class Shareable
|
---|
| 2600 | {
|
---|
| 2601 | public:
|
---|
| 2602 |
|
---|
| 2603 | Shareable() : mData (NULL), mIsShared (FALSE) {}
|
---|
| 2604 | ~Shareable() { free(); }
|
---|
| 2605 |
|
---|
| 2606 | void allocate() { attach (new D); }
|
---|
| 2607 |
|
---|
| 2608 | virtual void free() {
|
---|
| 2609 | if (mData) {
|
---|
| 2610 | if (!mIsShared)
|
---|
| 2611 | delete mData;
|
---|
| 2612 | mData = NULL;
|
---|
| 2613 | mIsShared = false;
|
---|
| 2614 | }
|
---|
| 2615 | }
|
---|
| 2616 |
|
---|
| 2617 | void attach (D *data) {
|
---|
| 2618 | AssertMsg (data, ("new data must not be NULL"));
|
---|
| 2619 | if (data && mData != data) {
|
---|
| 2620 | if (mData && !mIsShared)
|
---|
| 2621 | delete mData;
|
---|
| 2622 | mData = data;
|
---|
| 2623 | mIsShared = false;
|
---|
| 2624 | }
|
---|
| 2625 | }
|
---|
| 2626 |
|
---|
| 2627 | void attach (Shareable &data) {
|
---|
| 2628 | AssertMsg (
|
---|
| 2629 | data.mData == mData || !data.mIsShared,
|
---|
| 2630 | ("new data must not be shared")
|
---|
| 2631 | );
|
---|
| 2632 | if (this != &data && !data.mIsShared) {
|
---|
| 2633 | attach (data.mData);
|
---|
| 2634 | data.mIsShared = true;
|
---|
| 2635 | }
|
---|
| 2636 | }
|
---|
| 2637 |
|
---|
| 2638 | void share (D *data) {
|
---|
| 2639 | AssertMsg (data, ("new data must not be NULL"));
|
---|
| 2640 | if (mData != data) {
|
---|
| 2641 | if (mData && !mIsShared)
|
---|
| 2642 | delete mData;
|
---|
| 2643 | mData = data;
|
---|
| 2644 | mIsShared = true;
|
---|
| 2645 | }
|
---|
| 2646 | }
|
---|
| 2647 |
|
---|
| 2648 | void share (const Shareable &data) { share (data.mData); }
|
---|
| 2649 |
|
---|
| 2650 | void attachCopy (const D *data) {
|
---|
| 2651 | AssertMsg (data, ("data to copy must not be NULL"));
|
---|
| 2652 | if (data)
|
---|
| 2653 | attach (new D (*data));
|
---|
| 2654 | }
|
---|
| 2655 |
|
---|
| 2656 | void attachCopy (const Shareable &data) {
|
---|
| 2657 | attachCopy (data.mData);
|
---|
| 2658 | }
|
---|
| 2659 |
|
---|
| 2660 | virtual D *detach() {
|
---|
| 2661 | D *d = mData;
|
---|
| 2662 | mData = NULL;
|
---|
| 2663 | mIsShared = false;
|
---|
| 2664 | return d;
|
---|
| 2665 | }
|
---|
| 2666 |
|
---|
| 2667 | D *data() const {
|
---|
| 2668 | return mData;
|
---|
| 2669 | }
|
---|
| 2670 |
|
---|
| 2671 | D *operator->() const {
|
---|
| 2672 | AssertMsg (mData, ("data must not be NULL"));
|
---|
| 2673 | return mData;
|
---|
| 2674 | }
|
---|
| 2675 |
|
---|
| 2676 | bool isNull() const { return mData == NULL; }
|
---|
| 2677 | bool operator!() const { return isNull(); }
|
---|
| 2678 |
|
---|
| 2679 | bool isShared() const { return mIsShared; }
|
---|
| 2680 |
|
---|
| 2681 | protected:
|
---|
| 2682 |
|
---|
| 2683 | D *mData;
|
---|
| 2684 | bool mIsShared;
|
---|
| 2685 | };
|
---|
| 2686 |
|
---|
| 2687 | /// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
|
---|
| 2688 | /**
|
---|
| 2689 | * Simple template that enhances Shareable<> and supports data
|
---|
| 2690 | * backup/rollback/commit (using the copy constructor of the managed data
|
---|
| 2691 | * structure).
|
---|
| 2692 | */
|
---|
| 2693 | template <class D>
|
---|
| 2694 | class Backupable : public Shareable <D>
|
---|
| 2695 | {
|
---|
| 2696 | public:
|
---|
| 2697 |
|
---|
| 2698 | Backupable() : Shareable <D> (), mBackupData (NULL) {}
|
---|
| 2699 |
|
---|
| 2700 | void free()
|
---|
| 2701 | {
|
---|
| 2702 | AssertMsg (this->mData || !mBackupData, ("backup must be NULL if data is NULL"));
|
---|
| 2703 | rollback();
|
---|
| 2704 | Shareable <D>::free();
|
---|
| 2705 | }
|
---|
| 2706 |
|
---|
| 2707 | D *detach()
|
---|
| 2708 | {
|
---|
| 2709 | AssertMsg (this->mData || !mBackupData, ("backup must be NULL if data is NULL"));
|
---|
| 2710 | rollback();
|
---|
| 2711 | return Shareable <D>::detach();
|
---|
| 2712 | }
|
---|
| 2713 |
|
---|
| 2714 | void share (const Backupable &data)
|
---|
| 2715 | {
|
---|
| 2716 | AssertMsg (!data.isBackedUp(), ("data to share must not be backed up"));
|
---|
| 2717 | if (!data.isBackedUp())
|
---|
| 2718 | Shareable <D>::share (data.mData);
|
---|
| 2719 | }
|
---|
| 2720 |
|
---|
| 2721 | /**
|
---|
| 2722 | * Stores the current data pointer in the backup area, allocates new data
|
---|
| 2723 | * using the copy constructor on current data and makes new data active.
|
---|
| 2724 | */
|
---|
| 2725 | void backup()
|
---|
| 2726 | {
|
---|
| 2727 | AssertMsg (this->mData, ("data must not be NULL"));
|
---|
| 2728 | if (this->mData && !mBackupData)
|
---|
| 2729 | {
|
---|
| 2730 | mBackupData = this->mData;
|
---|
| 2731 | this->mData = new D (*mBackupData);
|
---|
| 2732 | }
|
---|
| 2733 | }
|
---|
| 2734 |
|
---|
| 2735 | /**
|
---|
| 2736 | * Deletes new data created by #backup() and restores previous data pointer
|
---|
| 2737 | * stored in the backup area, making it active again.
|
---|
| 2738 | */
|
---|
| 2739 | void rollback()
|
---|
| 2740 | {
|
---|
| 2741 | if (this->mData && mBackupData)
|
---|
| 2742 | {
|
---|
| 2743 | delete this->mData;
|
---|
| 2744 | this->mData = mBackupData;
|
---|
| 2745 | mBackupData = NULL;
|
---|
| 2746 | }
|
---|
| 2747 | }
|
---|
| 2748 |
|
---|
| 2749 | /**
|
---|
| 2750 | * Commits current changes by deleting backed up data and clearing up the
|
---|
| 2751 | * backup area. The new data pointer created by #backup() remains active
|
---|
| 2752 | * and becomes the only managed pointer.
|
---|
| 2753 | *
|
---|
| 2754 | * This method is much faster than #commitCopy() (just a single pointer
|
---|
| 2755 | * assignment operation), but makes the previous data pointer invalid
|
---|
| 2756 | * (because it is freed). For this reason, this method must not be
|
---|
| 2757 | * used if it's possible that data managed by this instance is shared with
|
---|
| 2758 | * some other Shareable instance. See #commitCopy().
|
---|
| 2759 | */
|
---|
| 2760 | void commit()
|
---|
| 2761 | {
|
---|
| 2762 | if (this->mData && mBackupData)
|
---|
| 2763 | {
|
---|
| 2764 | if (!this->mIsShared)
|
---|
| 2765 | delete mBackupData;
|
---|
| 2766 | mBackupData = NULL;
|
---|
| 2767 | this->mIsShared = false;
|
---|
| 2768 | }
|
---|
| 2769 | }
|
---|
| 2770 |
|
---|
| 2771 | /**
|
---|
| 2772 | * Commits current changes by assigning new data to the previous data
|
---|
| 2773 | * pointer stored in the backup area using the assignment operator.
|
---|
| 2774 | * New data is deleted, the backup area is cleared and the previous data
|
---|
| 2775 | * pointer becomes active and the only managed pointer.
|
---|
| 2776 | *
|
---|
| 2777 | * This method is slower than #commit(), but it keeps the previous data
|
---|
| 2778 | * pointer valid (i.e. new data is copied to the same memory location).
|
---|
| 2779 | * For that reason it's safe to use this method on instances that share
|
---|
| 2780 | * managed data with other Shareable instances.
|
---|
| 2781 | */
|
---|
| 2782 | void commitCopy()
|
---|
| 2783 | {
|
---|
| 2784 | if (this->mData && mBackupData)
|
---|
| 2785 | {
|
---|
| 2786 | *mBackupData = *(this->mData);
|
---|
| 2787 | delete this->mData;
|
---|
| 2788 | this->mData = mBackupData;
|
---|
| 2789 | mBackupData = NULL;
|
---|
| 2790 | }
|
---|
| 2791 | }
|
---|
| 2792 |
|
---|
| 2793 | void assignCopy (const D *data)
|
---|
| 2794 | {
|
---|
| 2795 | AssertMsg (this->mData, ("data must not be NULL"));
|
---|
| 2796 | AssertMsg (data, ("data to copy must not be NULL"));
|
---|
| 2797 | if (this->mData && data)
|
---|
| 2798 | {
|
---|
| 2799 | if (!mBackupData)
|
---|
| 2800 | {
|
---|
| 2801 | mBackupData = this->mData;
|
---|
| 2802 | this->mData = new D (*data);
|
---|
| 2803 | }
|
---|
| 2804 | else
|
---|
| 2805 | *this->mData = *data;
|
---|
| 2806 | }
|
---|
| 2807 | }
|
---|
| 2808 |
|
---|
| 2809 | void assignCopy (const Backupable &data)
|
---|
| 2810 | {
|
---|
| 2811 | assignCopy (data.mData);
|
---|
| 2812 | }
|
---|
| 2813 |
|
---|
| 2814 | bool isBackedUp() const
|
---|
| 2815 | {
|
---|
| 2816 | return mBackupData != NULL;
|
---|
| 2817 | }
|
---|
| 2818 |
|
---|
| 2819 | bool hasActualChanges() const
|
---|
| 2820 | {
|
---|
| 2821 | AssertMsg (this->mData, ("data must not be NULL"));
|
---|
| 2822 | return this->mData != NULL && mBackupData != NULL &&
|
---|
| 2823 | !(*this->mData == *mBackupData);
|
---|
| 2824 | }
|
---|
| 2825 |
|
---|
| 2826 | D *backedUpData() const
|
---|
| 2827 | {
|
---|
| 2828 | return mBackupData;
|
---|
| 2829 | }
|
---|
| 2830 |
|
---|
| 2831 | protected:
|
---|
| 2832 |
|
---|
| 2833 | D *mBackupData;
|
---|
| 2834 | };
|
---|
| 2835 |
|
---|
| 2836 | #endif // ____H_VIRTUALBOXBASEIMPL
|
---|