VirtualBoxBase.cpp revision f32de6c198a491c28ace2b4c53f8d04a79fd6d69
/* $Id$ */
/** @file
*
* VirtualBox COM base classes implementation
*/
/*
* Copyright (C) 2006-2009 Sun Microsystems, Inc.
*
* 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.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#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 "VirtualBoxErrorInfoImpl.h"
#include "Logging.h"
// VirtualBoxBaseProto methods
////////////////////////////////////////////////////////////////////////////////
{
mCallers = 0;
mInitUninitWaiters = 0;
mObjectLock = NULL;
}
{
if (mObjectLock)
delete mObjectLock;
Assert (mInitUninitWaiters == 0);
if (mZeroCallersSem != NIL_RTSEMEVENT)
mCallers = 0;
}
// util::Lockable interface
{
/* lazy initialization */
if (RT_UNLIKELY(!mObjectLock))
{
AssertCompile (sizeof (RWLockHandle *) == sizeof (void *));
{
delete objLock;
}
return objLock;
}
return mObjectLock;
}
/**
* Increments the number of calls to this object by one.
*
* After this method succeeds, it is guaranted 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 succeeeds (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
* succeeed 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.
*
* Also, addCaller() will block if the object is probing uninitialization on
* another thread with AutoMayUninitSpan (i.e. the object state is MayUninit).
* And again, the block will last until the AutoMayUninitSpan destructor signals
* that it has finished probing and the object is either ready again or will
* uninitialize shortly (so that addCaller() will fail).
*
* 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 overriden 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 preferrable 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 or AutoMayUninitSpan, just succeed */
}
{
/* One of the two:
*
* 1) addCaller() is called by a "child" thread while the "parent"
* thread is still doing AutoInitSpan/AutoReinitSpan, so wait for
* case of init failure).
*
* 2) addCaller() is called while another thread is in
* AutoMayUninitSpan, so wait for the state to become either
* Ready or WillUninit.
*
* Note that in either case 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);
}
"Waiting for AutoInitSpan/AutoReinitSpan to "
"finish...\n" :
"Waiting for AutoMayUninitSpan 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)
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 VirtualBoxBaseProto::releaseCaller()
{
{
/* if Ready or Limited, decrease the number of callers */
-- mCallers;
return;
}
{
if (mStateChangeThread == RTThreadSelf())
{
/* Called from the same thread that is doing AutoInitSpan,
* AutoMayUninitSpan or AutoUninitSpan: just succeed */
return;
}
{
/* the caller is being released after AutoUninitSpan or
* AutoMayUninitSpan has begun */
-- mCallers;
if (mCallers == 0)
{
/* inform the Auto*UninitSpan ctor there are no more callers */
}
return;
}
}
}
// VirtualBoxBaseProto::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.
*/
{
}
/**
* 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
{
/* leave 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()) */
}
}
// VirtualBoxBaseProto::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.
*/
{
}
/**
* 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
{
}
}
// VirtualBoxBaseProto::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.
*/
{
/* 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).
* In particular, this is used by
* VirtualBoxBaseWithTypedChildrenNEXT::uninitDependentChildren(). */
/* lazy semaphore creation */
{
}
++ mObj->mInitUninitWaiters;
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;
}
// VirtualBoxBaseProto::AutoMayUninitSpan methods
////////////////////////////////////////////////////////////////////////////////
/**
* Creates a smart initialization span object that places the object to
* MayUninit state.
*
* Please see the AutoMayUninitSpan class description for more info.
*
* @param aObj |this| pointer of the managed VirtualBoxBase object whose
* uninit() method to be probably called.
*/
, mAcceptUninit (false)
{
{
case Ready:
break;
case MayUninit:
/* Nothing to be done if already in MayUninit. */
mAlreadyInProgress = true;
return;
default:
/* Abuse mObj->addCaller() to get the extended error info possibly
* set by reimplementations of addCaller() and return it to the
* caller. Note that this abuse is supposed to be safe because we
* should've filtered out all states where addCaller() would do
* something else but set error info. */
return;
}
/* go to MayUninit to cause new callers to wait until we finish */
/* 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 back to Ready state if
* #acceptUninit() was not called, or places it to WillUninit state and calls
* the object's uninit() method.
*
* Please see the AutoMayUninitSpan class description for more info.
*/
{
/* if we did nothing in the constructor, do nothing here */
return;
{
/* We have some pending addCaller() calls on other threads made after
* going to during MayUnit, signal that MayUnit is finished and they may
* go on. */
}
if (!mAcceptUninit)
{
}
else
{
/* leave the lock to prevent nesting when uninit() is called */
/* call uninit() to let the object uninit itself */
/* Note: the object may no longer exist here (for example, it can call
* the destructor in uninit()) */
}
}
// VirtualBoxBase methods
////////////////////////////////////////////////////////////////////////////////
/**
* Translates the given text string according to the currently installed
* translation table and current context. The current context is determined
* by the context parameter. Additionally, a comment to the source text
* string text can be given. This comment (which is NULL by default)
* is helpful in situations where it is necessary to distinguish between
* two or more semantically different roles of the same source text in the
* same context.
*
* @param context the context of the translation (can be NULL
* to indicate the global context)
* @param sourceText the string to translate
* @param comment the comment to the string (NULL means no comment)
*
* @return
* the translated version of the source string in UTF-8 encoding,
* or the source string itself if the translation is not found
* in the given context.
*/
// static
const char * /* comment */)
{
#if 0
Log(("VirtualBoxBase::translate:\n"
" context={%s}\n"
" sourceT={%s}\n"
" comment={%s}\n",
#endif
/// @todo (dmik) incorporate Qt translation file parsing and lookup
return sourceText;
}
// VirtualBoxSupportTranslationBase methods
////////////////////////////////////////////////////////////////////////////////
/**
* Modifies the given argument so that it will contain only a class name
* (null-terminated). The argument must point to a <b>non-constant</b>
* string containing a valid value, as it is generated by the
* __PRETTY_FUNCTION__ built-in macro of the GCC compiler, or by the
* __FUNCTION__ macro of any other compiler.
*
* The function assumes that the macro is used within the member of the
* class derived from the VirtualBoxSupportTranslation<> template.
*
* @param prettyFunctionName string to modify
* @return
* true on success and false otherwise
*/
{
if (!fn)
return false;
#if defined (__GNUC__)
// the format is like:
// VirtualBoxSupportTranslation<C>::VirtualBoxSupportTranslation() [with C = VirtualBox]
#define START " = "
#define END "]"
// the format is like:
// VirtualBoxSupportTranslation<class VirtualBox>::__ctor
#define START "<class "
#define END ">::"
#endif
if (start)
{
{
return true;
}
}
return false;
}
// VirtualBoxSupportErrorInfoImplBase methods
////////////////////////////////////////////////////////////////////////////////
{
{
sCounter = RTTlsAlloc();
}
++ counter;
}
{
AssertReturnVoid (counter != 0);
-- counter;
}
/**
* 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 */
{
/* whether multi-error mode is turned on */
if (aLogIt)
LogRel (("ERROR [COM]: aRC=%Rhrc (%#08x) aIID={%RTuuid} aComponent={%ls} aText={%ls} "
"aWarning=%RTbool, preserve=%RTbool\n",
preserve));
/* these are mandatory, others -- not */
E_FAIL);
/* reset the error severity bit if it's a warning */
if (aWarning)
aResultCode &= ~0x80000000;
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);
}
// VirtualBoxBaseWithChildren methods
////////////////////////////////////////////////////////////////////////////////
/**
* Uninitializes all dependent children registered with #addDependentChild().
*
* @note
* This method will call uninit() methods of children. If these methods
* access the parent object, uninitDependentChildren() must be called
* either at the beginning of the parent uninitialization sequence (when
* it is still operational) or after setReady(false) is called to
* indicate the parent is out of action.
*/
{
/// @todo (r=dmik) see todo in VirtualBoxBase.h, in
// template <class C> void removeDependentChild (C *child)
AutoWriteLock alock (this);
if (mDependentChildren.size())
{
/* We keep the lock until we have enumerated all children.
* Those ones that will try to call #removeDependentChild() from
* a different thread will have to wait */
Assert (mChildrenLeft == 0);
{
if (child)
}
}
/* Wait until all children started uninitializing on their own
* (and therefore are waiting for some parent's method or for
* #removeDependentChild() to return) are finished uninitialization */
if (mUninitDoneSem != NIL_RTSEMEVENT)
{
/* let stuck children run */
LogFlowThisFunc (("Waiting for uninitialization of all children...\n"));
Assert (mChildrenLeft == 0);
}
}
/**
* Returns a pointer to the dependent child corresponding to the given
* interface pointer (used as a key in the map) or NULL if the interface
* pointer doesn't correspond to any child registered using
* #addDependentChild().
*
* @param unk
* Pointer to map to the dependent child object (it is ComPtr <IUnknown>
* rather than IUnknown *, to guarantee IUnknown * identity)
* @return
* Pointer to the dependent child object
*/
{
if (mUninitDoneSem != NIL_RTSEMEVENT)
return NULL;
return NULL;
}
/** Helper for addDependentChild() template method */
{
if (mUninitDoneSem != NIL_RTSEMEVENT)
{
// for this very unlikely case, we have to increase the number of
// children left, for symmetry with #removeDependentChild()
++ mChildrenLeft;
return;
}
}
/** Helper for removeDependentChild() template method */
{
/// @todo (r=dmik) see todo in VirtualBoxBase.h, in
// template <class C> void removeDependentChild (C *child)
AssertReturn (!!unk, (void) 0);
if (mUninitDoneSem != NIL_RTSEMEVENT)
{
// uninitDependentChildren() is in action, just increase the number
// of children left and signal a semaphore when it reaches zero
Assert (mChildrenLeft != 0);
-- mChildrenLeft;
if (mChildrenLeft == 0)
{
}
return;
}
}
// VirtualBoxBaseWithChildrenNEXT methods
////////////////////////////////////////////////////////////////////////////////
/**
* Uninitializes all dependent children registered on this object with
* #addDependentChild().
*
* Must be called from within the VirtualBoxBaseProto::AutoUninitSpan (i.e.
* typically from this object's uninit() method) to uninitialize children
* before this object goes out of service and becomes unusable.
*
* Note that this method will call uninit() methods of child objects. If
* these methods need to call the parent object during uninitialization,
* #uninitDependentChildren() must be called before the relevant part of the
* parent is uninitialized: usually at the begnning of the parent
* uninitialization sequence.
*
* Keep in mind that the uninitialized child objects may be no longer available
* (i.e. may be deleted) after this method returns.
*
* @note Locks #childrenLock() for writing.
*
* @note May lock something else through the called children.
*/
{
AutoCaller autoCaller (this);
/* sanity */
while (count != 0)
{
/* strongly reference the weak child from the map to make sure it won't
* be deleted while we've released the lock */
/* release the lock to let children stuck in removeDependentChild() go
* on (otherwise we'll deadlock in uninit() */
/* Note that if child->uninit() happens to be called on another
* thread right before us and is not yet finished, the second
* uninit() call will wait until the first one has done so
* (thanks to AutoUninitSpan). */
if (child)
/* uninit() is guaranteed to be done here so the child must be already
* deleted from the list by removeDependentChild() called from there.
* Do some checks to avoid endless loops when the user is forgetful */
-- count;
}
}
/**
* Returns a pointer to the dependent child (registered using
* #addDependentChild()) corresponding to the given interface pointer or NULL if
* the given pointer is unrelated.
*
* The relation is checked by using the given interface pointer as a key in the
* map of dependent children.
*
* Note that ComPtr <IUnknown> is used as an argument instead of IUnknown * in
* order to guarantee IUnknown identity and disambiguation by doing
* QueryInterface (IUnknown) rather than a regular C cast.
*
* @param aUnk Pointer to map to the dependent child object.
* @return Pointer to the dependent VirtualBoxBase child object.
*
* @note Locks #childrenLock() for reading.
*/
{
AutoCaller autoCaller (this);
/* return NULL if uninitDependentChildren() is in action */
return NULL;
return NULL;
}
/** Helper for addDependentChild(). */
{
AutoCaller autoCaller (this);
/* sanity */
}
/** Helper for removeDependentChild(). */
{
AutoCaller autoCaller (this);
/* sanity */
}
/* vi: set tabstop=4 shiftwidth=4 expandtab: */