Logo Search packages:      
Sourcecode: virtualbox-ose version File versions

VirtualBoxBaseWithChildren Class Reference

#include <VirtualBoxBase.h>

Inheritance diagram for VirtualBoxBaseWithChildren:

VirtualBoxBase VirtualBoxBaseProto util::Lockable

List of all members.

Detailed Description

Base class to track VirtualBoxBase children of the component.

This class is a preferable VirtualBoxBase replacement for components that operate with collections of child components. It gives two useful possibilities:

  1. Given an IUnknown instance, it's possible to quickly determine whether this instance represents a child object created by the given component, and if so, get a valid VirtualBoxBase pointer to the child object. The returned pointer can be then safely casted to the actual class of the child object (to get access to its "internal" non-interface methods) provided that no other child components implement the same initial interface IUnknown is queried from.
  2. When the parent object uninitializes itself, it can easily unintialize all its VirtualBoxBase derived children (using their VirtualBoxBase::uninit() implementations). This is done simply by calling the uninitDependentChildren() method.

In order to let the above work, the following must be done:

  1. When a child object is initialized, it calls addDependentChild() of its parent to register itself within the list of dependent children.
  2. When a child object it is uninitialized, it calls removeDependentChild() to unregister itself. This must be done after the child has called setReady(false) to indicate it is no more valid, and not from under the child object's lock. Note also, that the first action the child's uninit() implementation must do is to check for readiness after acquiring the object's lock and return immediately if not ready.

Children added by addDependentChild() are weakly referenced (i.e. AddRef() is not called), so when a child is externally destructed (i.e. its reference count goes to zero), it will automatically remove itself from a map of dependent children, provided that it follows the rules described here.

Because of weak referencing, deadlocks and assertions are very likely if addDependentChild() or removeDependentChild() are used incorrectly (called at inappropriate times). Check the above rules once more.
Use VirtualBoxBaseWithChildrenNEXT for new classes.

Definition at line 1949 of file VirtualBoxBase.h.

Public Types

typedef AutoCallerBase< false > AutoCaller
typedef AutoCallerBase< true > AutoLimitedCaller
enum  State {
  NotReady, Ready, InInit, InUninit,
  InitFailed, Limited, MayUninit, WillUninit

Public Member Functions

virtual HRESULT addCaller (State *aState=NULL, bool aLimited=false)
template<class C>
void addDependentChild (C *child)
HRESULT addLimitedCaller (State *aState=NULL)
bool isLockedOnCurrentThread ()
bool isReady ()
bool isReady ()
bool isWriteLockOnCurrentThread ()
void lock ()
virtual RWLockHandlelockHandle () const
virtual void releaseCaller ()
template<class C>
void removeDependentChild (C *child)
LockOps * rlock ()
void setReady (bool isReady)
void setReady (bool isReady)
virtual void uninit ()
virtual void uninit ()
void unlock ()
LockOps * wlock ()

Static Public Member Functions

static const char * translate (const char *context, const char *sourceText, const char *comment=0)
static const char * translate (const char *context, const char *sourceText, const char *comment=0)

Protected Member Functions

VirtualBoxBasegetDependentChild (const ComPtr< IUnknown > &unk)
WriteLockHandlestateLockHandle ()
void uninitDependentChildren ()

Private Types

typedef std::map< IUnknown
*, VirtualBoxBase * > 

Private Member Functions

void addDependentChild (const ComPtr< IUnknown > &unk, VirtualBoxBase *child)
void removeDependentChild (const ComPtr< IUnknown > &unk)

Private Attributes

unsigned mChildrenLeft
DependentChildren mDependentChildren
WriteLockHandle mMapLock

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index