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

VirtualBoxBaseWithChildrenNEXT Class Reference

#include <VirtualBoxBase.h>

Inheritance diagram for VirtualBoxBaseWithChildrenNEXT:

VirtualBoxBaseNEXT VirtualBoxBase VirtualBoxBaseProto util::Lockable Console USBController SessionMachine SnapshotMachine VirtualBoxClassFactory

List of all members.


Detailed Description

Base class to track VirtualBoxBaseNEXT chlidren of the component.

This class is a preferrable 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 that belongs to 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 original COM 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 the child object it is uninitialized, it calls removeDependentChild() to unregister itself.

Note that if the parent object does not call uninitDependentChildren() when it gets uninitialized, it must call uninit() methods of individual children manually to disconnect them; a failure to do so will cause crashes in these methods when children get destroyed. The same applies to children not calling removeDependentChild() when getting destroyed.

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

Access to the child list is serialized using the childrenLock() lock handle (which defaults to the general object lock handle (see VirtualBoxBase::lockHandle()). This lock is used by all add/remove methods of this class so be aware of the need to preserve the {parent, child} lock order when calling these methods.

Read individual method descriptions to get further information.

Todo:
This is a VirtualBoxBaseWithChildren equivalent that uses the VirtualBoxBaseNEXT implementation. Will completely supersede VirtualBoxBaseWithChildren after the old VirtualBoxBase implementation has gone.

Definition at line 2085 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 (const ComObjPtr< C > &aChild)
template<class C>
void addDependentChild (C *aChild)
HRESULT addLimitedCaller (State *aState=NULL)
virtual RWLockHandlechildrenLock ()
bool isLockedOnCurrentThread ()
bool isWriteLockOnCurrentThread ()
virtual RWLockHandlelockHandle () const
virtual void releaseCaller ()
template<class C>
void removeDependentChild (const ComObjPtr< C > &aChild)
template<class C>
void removeDependentChild (C *aChild)
LockOps * rlock ()
virtual void uninit ()
virtual void uninit ()
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

VirtualBoxBaseNEXTgetDependentChild (const ComPtr< IUnknown > &aUnk)
WriteLockHandlestateLockHandle ()
void uninitDependentChildren ()

Private Types

typedef std::map< IUnknown
*, VirtualBoxBaseNEXT * > 
DependentChildren

Private Member Functions

void doAddDependentChild (IUnknown *aUnk, VirtualBoxBaseNEXT *aChild)
void doAddDependentChild (IUnknown *aUnk, VirtualBoxBase *aChild)
void doRemoveDependentChild (IUnknown *aUnk)

Private Attributes

DependentChildren mDependentChildren

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

Generated by  Doxygen 1.6.0   Back to index