VirtualBoxBase.cpp revision 8324e598ca07b113321adec8ba2b95cd0eaabafc
/* $Id$ */
/** @file
*
* VirtualBox COM base classes implementation
*/
/*
* Copyright (C) 2006-2012 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*/
#include <iprt/semaphore.h>
#if !defined (VBOX_WITH_XPCOM)
#include <windows.h>
#include <dbghelp.h>
#else /* !defined (VBOX_WITH_XPCOM) */
/// @todo remove when VirtualBoxErrorInfo goes away from here
#include <nsIServiceManager.h>
#include <nsIExceptionService.h>
#endif /* !defined (VBOX_WITH_XPCOM) */
#include "VirtualBoxBase.h"
#include "AutoCaller.h"
#include "VirtualBoxErrorInfoImpl.h"
#include "Logging.h"
#include "VBox/com/ErrorInfo.h"
#include "VBox/com/MultiResult.h"
////////////////////////////////////////////////////////////////////////////////
//
// VirtualBoxBase
//
////////////////////////////////////////////////////////////////////////////////
{
mCallers = 0;
mInitUninitWaiters = 0;
mObjectLock = NULL;
}
{
if (mObjectLock)
delete mObjectLock;
Assert(mInitUninitWaiters == 0);
if (mZeroCallersSem != NIL_RTSEMEVENT)
mCallers = 0;
}
/**
* This virtual method returns an RWLockHandle that can be used to
* protect instance data. This RWLockHandle is generally referred to
* as the "object lock"; its locking class (for lock order validation)
* must be returned by another virtual method, getLockingClass(), which
* by default returns LOCKCLASS_OTHEROBJECT but is overridden by several
* subclasses such as VirtualBox, Host, Machine and others.
*
* On the first call this method lazily creates the RWLockHandle.
*
* @return
*/
/* virtual */
{
/* lazy initialization */
if (RT_UNLIKELY(!mObjectLock))
{
AssertCompile (sizeof (RWLockHandle *) == sizeof (void *));
// getLockingClass() is overridden by many subclasses to return
// one of the locking classes listed at the top of AutoLock.h
{
delete objLock;
}
return objLock;
}
return mObjectLock;
}
/**
* Increments the number of calls to this object by one.
*
* After this method succeeds, it is guaranteed that the object will remain
* in the Ready (or in the Limited) state at least until #releaseCaller() is
* called.
*
* This method is intended to mark the beginning of sections of code within
* methods of COM objects that depend on the readiness (Ready) state. The
* Ready state is a primary "ready to serve" state. Usually all code that
* works with component's data depends on it. On practice, this means that
* almost every public method, setter or getter of the object should add
* itself as an object's caller at the very beginning, to protect from an
* unexpected uninitialization that may happen on a different thread.
*
* Besides the Ready state denoting that the object is fully functional,
* there is a special Limited state. The Limited state means that the object
* is still functional, but its functionality is limited to some degree, so
* not all operations are possible. The @a aLimited argument to this method
* determines whether the caller represents this limited functionality or
* not.
*
* This method succeeds (and increments the number of callers) only if the
* current object's state is Ready. Otherwise, it will return E_ACCESSDENIED
* to indicate that the object is not operational. There are two exceptions
* from this rule:
* <ol>
* <li>If the @a aLimited argument is |true|, then this method will also
* succeed if the object's state is Limited (or Ready, of course).
* </li>
* <li>If this method is called from the same thread that placed
* the object to InInit or InUninit state (i.e. either from within the
* AutoInitSpan or AutoUninitSpan scope), it will succeed as well (but
* will not increase the number of callers).
* </li>
* </ol>
*
* Normally, calling addCaller() never blocks. However, if this method is
* called by a thread created from within the AutoInitSpan scope and this
* scope is still active (i.e. the object state is InInit), it will block
* until the AutoInitSpan destructor signals that it has finished
* initialization.
*
* When this method returns a failure, the caller must not use the object
* and should return the failed result code to its own caller.
*
* @param aState Where to store the current object's state (can be
* used in overridden methods to determine the cause of
* the failure).
* @param aLimited |true| to add a limited caller.
*
* @return S_OK on success or E_ACCESSDENIED on failure.
*
* @note It is preferable to use the #addLimitedCaller() rather than
* calling this method with @a aLimited = |true|, for better
* self-descriptiveness.
*
* @sa #addLimitedCaller()
* @sa #releaseCaller()
*/
bool aLimited /* = false */)
{
{
/* if Ready or allows Limited, increase the number of callers */
++ mCallers;
}
else
{
if (mStateChangeThread == RTThreadSelf())
{
/* Called from the same thread that is doing AutoInitSpan or
* AutoUninitSpan, just succeed */
}
{
/* addCaller() is called by a "child" thread while the "parent"
* thread is still doing AutoInitSpan/AutoReinitSpan, so wait for
* case of init failure).
*
* Note that we increase the number of callers anyway -- to
* prevent AutoUninitSpan from early completion if we are
* still not scheduled to pick up the posted semaphore when
* uninit() is called.
*/
++ mCallers;
/* lazy semaphore creation */
if (mInitUninitSem == NIL_RTSEMEVENTMULTI)
{
Assert(mInitUninitWaiters == 0);
}
LogFlowThisFunc(("Waiting for AutoInitSpan/AutoReinitSpan to finish...\n"));
if (-- mInitUninitWaiters == 0)
{
/* destroy the semaphore since no more necessary */
}
else
{
-- mCallers;
{
/* inform AutoUninitSpan ctor there are no more callers */
}
}
}
}
if (aState)
{
else
}
return rc;
}
/**
* Decreases the number of calls to this object by one.
*
* Must be called after every #addCaller() or #addLimitedCaller() when
* protecting the object from uninitialization is no more necessary.
*/
void VirtualBoxBase::releaseCaller()
{
{
/* if Ready or Limited, decrease the number of callers */
--mCallers;
return;
}
{
if (mStateChangeThread == RTThreadSelf())
{
/* Called from the same thread that is doing AutoInitSpan or
* AutoUninitSpan: just succeed */
return;
}
{
/* the caller is being released after AutoUninitSpan has begun */
--mCallers;
if (mCallers == 0)
/* inform the Auto*UninitSpan ctor there are no more callers */
return;
}
}
}
/**
* Sets error info for the current thread. This is an internal function that
* gets eventually called by all public variants. If @a aWarning is
* @c true, then the highest (31) bit in the @a aResultCode value which
* indicates the error severity is reset to zero to make sure the receiver will
* recognize that the created error info object represents a warning rather
* than an error.
*/
/* static */
const char *pcszComponent,
bool aWarning,
bool aLogIt)
{
/* whether multi-error mode is turned on */
if (aLogIt)
LogRel(("%s [COM]: aRC=%Rhrc (%#08x) aIID={%RTuuid} aComponent={%s} aText={%s}, preserve=%RTbool\n",
&aIID,
preserve));
/* these are mandatory, others -- not */
E_FAIL);
/* reset the error severity bit if it's a warning */
if (aWarning)
aResultCode &= ~0x80000000;
{
/* Some default info */
switch (aResultCode)
{
case VBOX_E_OBJECT_NOT_FOUND: aText = "Object corresponding to the supplied arguments does not exist"; break;
case VBOX_E_INVALID_VM_STATE: aText = "Current virtual machine state prevents the operation"; break;
default: aText = "Unknown error"; break;
}
}
do
{
#if !defined (VBOX_WITH_XPCOM)
if (preserve)
{
/* get the current error info if any */
{
/* create a IVirtualBoxErrorInfo wrapper for the native
* IErrorInfo object */
{
}
}
}
/* On failure, curInfo will stay null */
/* set the current error info and preserve the previous one if any */
#else // !defined (VBOX_WITH_XPCOM)
if (NS_SUCCEEDED(rc))
{
if (preserve)
{
/* get the current error info if any */
{
/* create a IVirtualBoxErrorInfo wrapper for the native
* nsIException object */
{
}
}
}
/* On failure, curInfo will stay null */
/* set the current error info and preserve the previous one if any */
}
else if (rc == NS_ERROR_UNEXPECTED)
{
/*
* It is possible that setError() is being called by the object
* after the XPCOM shutdown sequence has been initiated
* (for example, when XPCOM releases all instances it internally
* references, which can cause object's FinalConstruct() and then
* uninit()). In this case, do_GetService() above will return
* NS_ERROR_UNEXPECTED and it doesn't actually make sense to
* set the exception (nobody will be able to read it).
*/
LogWarningFunc(("Will not set an exception because nsIExceptionService is not available "
"(NS_ERROR_UNEXPECTED). XPCOM is being shutdown?\n"));
}
#endif // !defined (VBOX_WITH_XPCOM)
}
while (0);
AssertComRC (rc);
}
/**
* Shortcut instance method to calling the static setErrorInternal with the
* class interface ID and component name inserted correctly. This uses the
* virtual getClassIID() and getComponentName() methods which are automatically
* defined by the VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT macro.
* @param aResultCode
* @param pcsz
* @return
*/
{
return setErrorInternal(aResultCode,
this->getClassIID(),
this->getComponentName(),
"",
false /* aWarning */,
true /* aLogIt */);
}
/**
* Shortcut instance method to calling the static setErrorInternal with the
* class interface ID and component name inserted correctly. This uses the
* virtual getClassIID() and getComponentName() methods which are automatically
* defined by the VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT macro.
* @param aResultCode
* @return
*/
{
this->getClassIID(),
this->getComponentName(),
false /* aWarning */,
true /* aLogIt */);
return rc;
}
/**
* Shortcut instance method to calling the static setErrorInternal with the
* class interface ID and component name inserted correctly. This uses the
* virtual getClassIID() and getComponentName() methods which are automatically
* defined by the VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT macro.
* @param ei
* @return
*/
{
/* whether multi-error mode is turned on */
do
{
#if !defined (VBOX_WITH_XPCOM)
if (preserve)
{
/* get the current error info if any */
{
/* create a IVirtualBoxErrorInfo wrapper for the native
* IErrorInfo object */
{
}
}
}
/* On failure, curInfo will stay null */
/* set the current error info and preserve the previous one if any */
#else // !defined (VBOX_WITH_XPCOM)
if (NS_SUCCEEDED(rc))
{
if (preserve)
{
/* get the current error info if any */
{
/* create a IVirtualBoxErrorInfo wrapper for the native
* nsIException object */
{
}
}
}
/* On failure, curInfo will stay null */
/* set the current error info and preserve the previous one if any */
}
else if (rc == NS_ERROR_UNEXPECTED)
{
/*
* It is possible that setError() is being called by the object
* after the XPCOM shutdown sequence has been initiated
* (for example, when XPCOM releases all instances it internally
* references, which can cause object's FinalConstruct() and then
* uninit()). In this case, do_GetService() above will return
* NS_ERROR_UNEXPECTED and it doesn't actually make sense to
* set the exception (nobody will be able to read it).
*/
LogWarningFunc(("Will not set an exception because nsIExceptionService is not available "
"(NS_ERROR_UNEXPECTED). XPCOM is being shutdown?\n"));
}
#endif // !defined (VBOX_WITH_XPCOM)
}
while (0);
AssertComRC (rc);
}
/**
* Like setError(), but sets the "warning" bit in the call to setErrorInternal().
* @param aResultCode
* @param pcsz
* @return
*/
{
this->getClassIID(),
this->getComponentName(),
true /* aWarning */,
true /* aLogIt */);
return rc;
}
/**
* Like setError(), but disables the "log" flag in the call to setErrorInternal().
* @param aResultCode
* @param pcsz
* @return
*/
{
this->getClassIID(),
this->getComponentName(),
false /* aWarning */,
false /* aLogIt */);
return rc;
}
/**
* Clear the current error information.
*/
/*static*/
void VirtualBoxBase::clearError(void)
{
#if !defined(VBOX_WITH_XPCOM)
::SetErrorInfo (0, NULL);
#else
if (NS_SUCCEEDED(rc))
{
}
#endif
}
////////////////////////////////////////////////////////////////////////////////
//
// AutoInitSpan methods
//
////////////////////////////////////////////////////////////////////////////////
/**
* Creates a smart initialization span object that places the object to
* InInit state.
*
* Please see the AutoInitSpan class description for more info.
*
* @param aObj |this| pointer of the managed VirtualBoxBase object whose
* init() method is being called.
* @param aResult Default initialization result.
*/
mOk(false)
{
}
/**
* initialization succeeded or partly succeeded, or places it to InitFailed
* state and calls the object's uninit() method.
*
* Please see the AutoInitSpan class description for more info.
*/
{
/* if the state was other than NotReady, do nothing */
if (!mOk)
return;
{
/* We have some pending addCaller() calls on other threads (created
* during InInit), signal that InInit is finished and they may go on. */
}
{
}
else
{
}
else
{
/* release the lock to prevent nesting when uninit() is called */
/* call uninit() to let the object uninit itself after failed init() */
/* Note: the object may no longer exist here (for example, it can call
* the destructor in uninit()) */
}
}
// AutoReinitSpan methods
////////////////////////////////////////////////////////////////////////////////
/**
* Creates a smart re-initialization span object and places the object to
* InInit state.
*
* Please see the AutoInitSpan class description for more info.
*
* @param aObj |this| pointer of the managed VirtualBoxBase object whose
* re-initialization method is being called.
*/
mSucceeded(false),
mOk(false)
{
}
/**
* Places the managed VirtualBoxBase object to Ready state if the
* re-initialization succeeded (i.e. #setSucceeded() has been called) or back to
* Limited state otherwise.
*
* Please see the AutoInitSpan class description for more info.
*/
{
/* if the state was other than Limited, do nothing */
if (!mOk)
return;
{
/* We have some pending addCaller() calls on other threads (created
* during InInit), signal that InInit is finished and they may go on. */
}
if (mSucceeded)
{
}
else
{
}
}
// AutoUninitSpan methods
////////////////////////////////////////////////////////////////////////////////
/**
* Creates a smart uninitialization span object and places this object to
* InUninit state.
*
* Please see the AutoInitSpan class description for more info.
*
* @note This method blocks the current thread execution until the number of
* callers of the managed VirtualBoxBase object drops to zero!
*
* @param aObj |this| pointer of the VirtualBoxBase object whose uninit()
* method is being called.
*/
mInitFailed(false),
mUninitDone(false)
{
/* Set mUninitDone to |true| if this object is already uninitialized
* (NotReady) or if another AutoUninitSpan is currently active on some
* other thread (InUninit). */
{
/* we've been called by init() on failure */
mInitFailed = true;
}
else
{
if (mUninitDone)
{
/* do nothing if already uninitialized */
return;
/* otherwise, wait until another thread finishes uninitialization.
* This is necessary to make sure that when this method returns, the
* object is NotReady and therefore can be deleted (for example). */
/* lazy semaphore creation */
{
}
LogFlowFunc(("{%p}: Waiting for AutoUninitSpan to finish...\n",
mObj));
if (--mObj->mInitUninitWaiters == 0)
{
/* destroy the semaphore since no more necessary */
}
return;
}
}
/* go to InUninit to prevent from adding new callers */
/* wait for already existing callers to drop to zero */
{
/* lazy creation */
/* wait until remaining callers release the object */
LogFlowFunc(("{%p}: Waiting for callers (%d) to drop to zero...\n",
}
}
/**
* Places the managed VirtualBoxBase object to the NotReady state.
*/
{
/* do nothing if already uninitialized */
if (mUninitDone)
return;
}
////////////////////////////////////////////////////////////////////////////////
//
// MultiResult methods
//
////////////////////////////////////////////////////////////////////////////////
/*static*/
void MultiResult::incCounter()
{
{
sCounter = RTTlsAlloc();
}
++counter;
}
/*static*/
void MultiResult::decCounter()
{
AssertReturnVoid(counter != 0);
--counter;
}
/*static*/
bool MultiResult::isMultiEnabled()
{
return false;
}