84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * VirtualBox object caller handling definitions
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * Copyright (C) 2006-2014 Oracle Corporation
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * available from http://www.virtualbox.org. This file is free software;
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * you can redistribute it and/or modify it under the terms of the GNU
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * General Public License (GPL) as published by the Free Software
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync// Forward declaration needed, but nothing more.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync////////////////////////////////////////////////////////////////////////////////
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync// AutoCaller* classes
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync////////////////////////////////////////////////////////////////////////////////
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * Smart class that automatically increases the number of normal (non-limited)
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * callers of the given VirtualBoxBase object when an instance is constructed
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * and decreases it back when the created instance goes out of scope (i.e. gets
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * destroyed).
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * If #rc() returns a failure after the instance creation, it means that
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * the managed VirtualBoxBase object is not Ready, or in any other invalid
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * state, so that the caller must not use the object and can return this
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * failed result code to the upper level.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * See ObjectState::addCaller() and ObjectState::releaseCaller() for more
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * details about object callers.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * A typical usage pattern to declare a normal method of some object (i.e. a
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * method that is valid only when the object provides its full
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * functionality) is:
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * STDMETHODIMP Component::Foo()
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * AutoCaller autoCaller(this);
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * HRESULT hrc = autoCaller.rc();
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * if (SUCCEEDED(hrc))
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * return hrc;
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * Default constructor. Not terribly useful, but it's valid to create
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * an instance without associating it with an object. It's a no-op,
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * like the more useful constructor below when NULL is passed to it.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Increases the number of callers of the given object by calling
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * ObjectState::addCaller() for the corresponding member instance.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * @param aObj Object to add a normal caller to. If NULL, this
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * instance is effectively turned to no-op (where
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * rc() will return S_OK).
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * If the number of callers was successfully increased, decreases it
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * using ObjectState::releaseCaller(), otherwise does nothing.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * Returns the stored result code returned by ObjectState::addCaller()
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * after instance creation or after the last #add() call. A successful
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * result code means the number of callers was successfully increased.
4f7bc3e9b035984d494d38afa2913fa560e259d6vboxsync * Returns |true| if |SUCCEEDED(rc())| is |true|, for convenience.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * |true| means the number of callers was successfully increased.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Temporarily decreases the number of callers of the managed object.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * May only be called if #isOk() returns |true|. Note that #rc() will
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * return E_FAIL after this method succeeds.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Restores the number of callers decreased by #release(). May only be
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * called after #release().
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Attaches another object to this caller instance.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * The previous object's caller is released before the new one is added.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * @param aObj New object to attach, may be @c NULL.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync /* detect simple self-reattachment */
97b672c60368db8e7ba24563e516fc308e73b192vboxsync /* Fix up the success state when nothing is attached. Otherwise
97b672c60368db8e7ba24563e516fc308e73b192vboxsync * there are a couple of assertion which would trigger. */
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync /** Verbose equivalent to <tt>attach(NULL)</tt>. */
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * Internal constructor: Increases the number of callers of the given
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * object (either normal or limited variant) by calling
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * ObjectState::addCaller() for the corresponding member instance.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * @param aObj Object to add a caller to. If NULL, this
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * instance is effectively turned to no-op (where
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * rc() will return S_OK).
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * @param aLimited If |false|, then it's a regular caller, otherwise a
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * limited caller.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Smart class that automatically increases the number of limited callers of
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * the given VirtualBoxBase object when an instance is constructed and
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * decreases it back when the created instance goes out of scope (i.e. gets
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * destroyed).
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * A typical usage pattern to declare a limited method of some object (i.e.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * a method that is valid even if the object doesn't provide its full
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * functionality) is:
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * STDMETHODIMP Component::Bar()
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * AutoLimitedCaller autoCaller(this);
73f0af1b2489436ca88cd6af3ac73c9ce0da96a7vboxsync * HRESULT hrc = autoCaller.rc();
73f0af1b2489436ca88cd6af3ac73c9ce0da96a7vboxsync * if (SUCCEEDED(hrc))
73f0af1b2489436ca88cd6af3ac73c9ce0da96a7vboxsync * return hrc;
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * See AutoCaller for more information about auto caller functionality.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * Default constructor. Not terribly useful, but it's valid to create
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * an instance without associating it with an object. It's a no-op,
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * like the more useful constructor below when NULL is passed to it.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * Increases the number of callers of the given object by calling
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * ObjectState::addCaller() for the corresponding member instance.
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * @param aObj Object to add a limited caller to. If NULL, this
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * instance is effectively turned to no-op (where
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * rc() will return S_OK).
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Smart class to enclose the state transition NotReady->InInit->Ready.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * The purpose of this span is to protect object initialization.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Instances must be created as a stack-based variable taking |this| pointer
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * as the argument at the beginning of init() methods of VirtualBoxBase
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * subclasses. When this variable is created it automatically places the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * object to the InInit state.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * When the created variable goes out of scope (i.e. gets destroyed) then,
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * depending on the result status of this initialization span, it either
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * places the object to Ready or Limited state or calls the object's
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * VirtualBoxBase::uninit() method which is supposed to place the object
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * back to the NotReady state using the AutoUninitSpan class.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * The initial result status of the initialization span is determined by the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * @a aResult argument of the AutoInitSpan constructor (Result::Failed by
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * default). Inside the initialization span, the success status can be set
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * to Result::Succeeded using #setSucceeded(), to to Result::Limited using
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * #setLimited() or to Result::Failed using #setFailed(). Please don't
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * forget to set the correct success status before getting the AutoInitSpan
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * variable destroyed (for example, by performing an early return from
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * the init() method)!
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Note that if an instance of this class gets constructed when the object
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * is in the state other than NotReady, #isOk() returns |false| and methods
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * of this class do nothing: the state transition is not performed.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * A typical usage pattern is:
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * HRESULT Component::init()
73f0af1b2489436ca88cd6af3ac73c9ce0da96a7vboxsync * AutoInitSpan autoInitSpan(this);
73f0af1b2489436ca88cd6af3ac73c9ce0da96a7vboxsync * AssertReturn(autoInitSpan.isOk(), E_FAIL);
4f7bc3e9b035984d494d38afa2913fa560e259d6vboxsync * if (FAILED(rc))
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * return rc;
4f7bc3e9b035984d494d38afa2913fa560e259d6vboxsync * if (SUCCEEDED(rc))
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * autoInitSpan.setSucceeded();
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * return rc;
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * @note Never create instances of this class outside init() methods of
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * VirtualBoxBase subclasses and never pass anything other than |this|
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * as the argument to the constructor!
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync enum Result { Failed = 0x0, Succeeded = 0x1, Limited = 0x2 };
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync AutoInitSpan(VirtualBoxBase *aObj, Result aResult = Failed);
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Returns |true| if this instance has been created at the right moment
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * (when the object was in the NotReady state) and |false| otherwise.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Sets the initialization status to Succeeded to indicates successful
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * initialization. The AutoInitSpan destructor will place the managed
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * VirtualBoxBase object to the Ready state.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Sets the initialization status to Succeeded to indicate limited
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * (partly successful) initialization. The AutoInitSpan destructor will
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * place the managed VirtualBoxBase object to the Limited state.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Sets the initialization status to Failure to indicates failed
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * initialization. The AutoInitSpan destructor will place the managed
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * VirtualBoxBase object to the InitFailed state and will automatically
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * call its uninit() method which is supposed to place the object back
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * to the NotReady state using AutoUninitSpan.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync /** Returns the current initialization result. */
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync Result mResult : 3; // must be at least total number of bits + 1 (sign)
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Smart class to enclose the state transition Limited->InInit->Ready.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * The purpose of this span is to protect object re-initialization.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Instances must be created as a stack-based variable taking |this| pointer
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * as the argument at the beginning of methods of VirtualBoxBase
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * subclasses that try to re-initialize the object to bring it to the Ready
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * state (full functionality) after partial initialization (limited
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * functionality). When this variable is created, it automatically places
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * the object to the InInit state.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * When the created variable goes out of scope (i.e. gets destroyed),
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * depending on the success status of this initialization span, it either
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * places the object to the Ready state or brings it back to the Limited
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * The initial success status of the re-initialization span is |false|. In
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * order to make it successful, #setSucceeded() must be called before the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * instance is destroyed.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Note that if an instance of this class gets constructed when the object
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * is in the state other than Limited, #isOk() returns |false| and methods
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * of this class do nothing: the state transition is not performed.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * A typical usage pattern is:
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * HRESULT Component::reinit()
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * AutoReinitSpan autoReinitSpan(this);
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * AssertReturn(autoReinitSpan.isOk(), E_FAIL);
4f7bc3e9b035984d494d38afa2913fa560e259d6vboxsync * if (FAILED(rc))
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * return rc;
4f7bc3e9b035984d494d38afa2913fa560e259d6vboxsync * if (SUCCEEDED(rc))
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * autoReinitSpan.setSucceeded();
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * return rc;
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * @note Never create instances of this class outside re-initialization
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * methods of VirtualBoxBase subclasses and never pass anything other than
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * |this| as the argument to the constructor!
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Returns |true| if this instance has been created at the right moment
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * (when the object was in the Limited state) and |false| otherwise.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Sets the re-initialization status to Succeeded to indicates
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * successful re-initialization. The AutoReinitSpan destructor will place
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * the managed VirtualBoxBase object to the Ready state.
269c2f4da48ed34127db57078caf2016b0c19e5fvboxsync * Smart class to enclose the state transition Ready->InUninit->NotReady,
269c2f4da48ed34127db57078caf2016b0c19e5fvboxsync * InitFailed->InUninit->NotReady.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * The purpose of this span is to protect object uninitialization.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * Instances must be created as a stack-based variable taking |this| pointer
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * as the argument at the beginning of uninit() methods of VirtualBoxBase
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * subclasses. When this variable is created it automatically places the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * object to the InUninit state, unless it is already in the NotReady state
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * as indicated by #uninitDone() returning |true|. In the latter case, the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * uninit() method must immediately return because there should be nothing
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * to uninitialize.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * When this variable goes out of scope (i.e. gets destroyed), it places the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * object to NotReady state.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * A typical usage pattern is:
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * void Component::uninit()
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * AutoUninitSpan autoUninitSpan(this);
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * if (autoUninitSpan.uninitDone())
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * @note The constructor of this class blocks the current thread execution
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * until the number of callers added to the object using
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * ObjectState::addCaller() or AutoCaller drops to zero. For this reason,
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * it is forbidden to create instances of this class (or call uninit())
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * within the AutoCaller or ObjectState::addCaller() scope because it is
84029357bc8c5780585a1cd1b40319bbc23d022fvboxsync * a guaranteed deadlock.
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * @note Never create instances of this class outside uninit() methods and
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * never pass anything other than |this| as the argument to the
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync * constructor!
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync /** |true| when uninit() is called as a result of init() failure */
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync /** |true| when uninit() has already been called (so the object is NotReady) */
545a02e9eda0fc9d6be6f8513686228283f73627vboxsync#endif // !____H_AUTOCALLER