AutoCaller.cpp revision 84029357bc8c5780585a1cd1b40319bbc23d022f
/* $Id$ */
/** @file
*
* VirtualBox object state implementation
*/
/*
* Copyright (C) 2006-2014 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>
#include "VirtualBoxBase.h"
#include "AutoCaller.h"
#include "Logging.h"
////////////////////////////////////////////////////////////////////////////////
//
// ObjectState methods
//
////////////////////////////////////////////////////////////////////////////////
{
AssertFailed();
}
{
mCallers = 0;
mInitUninitWaiters = 0;
}
{
Assert(mInitUninitWaiters == 0);
if (mZeroCallersSem != NIL_RTSEMEVENT)
mCallers = 0;
}
{
return mState;
}
/**
* 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 aLimited |true| to add a limited caller.
*
* @return S_OK on success or E_ACCESSDENIED on failure.
*
* @sa #releaseCaller()
*/
{
{
/* 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 */
}
}
}
}
{
else
}
return rc;
}
/**
* Decreases the number of calls to this object by one.
*
* Must be called after every #addCaller() when protecting the object
* from uninitialization is no more necessary.
*/
void ObjectState::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;
}
}
}
{
if (mState == aExpectedState)
{
return true;
}
else
return false;
}
{
if (mCallers > 0 && mInitUninitWaiters > 0)
{
/* We have some pending addCaller() calls on other threads (created
* during InInit), signal that InInit is finished and they may go on. */
}
}
{
{
/* do nothing if already uninitialized */
return mState;
}
{
/* Another thread has already started uninitialization, wait for its
* completion. This is necessary to make sure that when this method
* returns, the object state is well-defined (NotReady). */
/* lazy semaphore creation */
if (mInitUninitSem == NIL_RTSEMEVENTMULTI)
{
Assert(mInitUninitWaiters == 0);
}
if (--mInitUninitWaiters == 0)
{
/* destroy the semaphore since no more necessary */
}
/* the other thread set it to NotReady */
return mState;
}
/* go to InUninit to prevent from adding new callers */
/* wait for already existing callers to drop to zero */
if (mCallers > 0)
{
/* lazy creation */
/* wait until remaining callers release the object */
LogFlowFunc(("{%p}: Waiting for callers (%d) to drop to zero...\n",
}
return mState;
}
void ObjectState::autoUninitSpanDestructor()
{
}
{
}
////////////////////////////////////////////////////////////////////////////////
//
// 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;
else
{
/* 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;
if (mSucceeded)
else
/** @todo r=klaus: this is like the initial init() failure, but in this
* place uninit() is NOT called. Makes only limited sense. */
}
// 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)
{
mInitFailed = true;
mUninitDone = true;
}
/**
* Places the managed VirtualBoxBase object to the NotReady state.
*/
{
/* do nothing if already uninitialized */
if (mUninitDone)
return;
}