VirtualBoxBase.cpp@ 25881

Last change on this file since 25881 was 25860, checked in by vboxsync, 15 years ago
Main: cleanup: get rid of VirtualBoxBaseProto, move AutoCaller/Span* classes out of VirtualBoxBaseProto class scope and into separate header; move CombinedProgress into separate header (it's only used by Console any more)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.2 KB

Line
1	/* $Id: VirtualBoxBase.cpp 25860 2010-01-15 13:27:26Z vboxsync $ */
2
3	/** @file
4	*
5	* VirtualBox COM base classes implementation
6	*/
7
8	/*
9	* Copyright (C) 2006-2009 Sun Microsystems, Inc.
10	*
11	* This file is part of VirtualBox Open Source Edition (OSE), as
12	* available from http://www.virtualbox.org. This file is free software;
13	* you can redistribute it and/or modify it under the terms of the GNU
14	* General Public License (GPL) as published by the Free Software
15	* Foundation, in version 2 as it comes in the "COPYING" file of the
16	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18	*
19	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
20	* Clara, CA 95054 USA or visit http://www.sun.com if you need
21	* additional information or have any questions.
22	*/
23
24	#include <iprt/semaphore.h>
25	#include <iprt/asm.h>
26
27	#if !defined (VBOX_WITH_XPCOM)
28	#include <windows.h>
29	#include <dbghelp.h>
30	#else /* !defined (VBOX_WITH_XPCOM) */
31	/// @todo remove when VirtualBoxErrorInfo goes away from here
32	#include <nsIServiceManager.h>
33	#include <nsIExceptionService.h>
34	#endif /* !defined (VBOX_WITH_XPCOM) */
35
36	#include "VirtualBoxBase.h"
37	#include "AutoCaller.h"
38	#include "VirtualBoxErrorInfoImpl.h"
39	#include "Logging.h"
40
41	#include "objectslist.h"
42
43	////////////////////////////////////////////////////////////////////////////////
44	//
45	// VirtualBoxBase
46	//
47	////////////////////////////////////////////////////////////////////////////////
48
49	VirtualBoxBase::VirtualBoxBase()
50	: mStateLock(LOCKCLASS_OBJECTSTATE)
51	{
52	mState = NotReady;
53	mStateChangeThread = NIL_RTTHREAD;
54	mCallers = 0;
55	mZeroCallersSem = NIL_RTSEMEVENT;
56	mInitUninitSem = NIL_RTSEMEVENTMULTI;
57	mInitUninitWaiters = 0;
58	mObjectLock = NULL;
59	}
60
61	VirtualBoxBase::~VirtualBoxBase()
62	{
63	if (mObjectLock)
64	delete mObjectLock;
65	Assert (mInitUninitWaiters == 0);
66	Assert (mInitUninitSem == NIL_RTSEMEVENTMULTI);
67	if (mZeroCallersSem != NIL_RTSEMEVENT)
68	RTSemEventDestroy (mZeroCallersSem);
69	mCallers = 0;
70	mStateChangeThread = NIL_RTTHREAD;
71	mState = NotReady;
72	}
73
74	/**
75	* This virtual method returns an RWLockHandle that can be used to
76	* protect instance data. This RWLockHandle is generally referred to
77	* as the "object lock"; its locking class (for lock order validation)
78	* must be returned by another virtual method, getLockingClass(), which
79	* by default returns LOCKCLASS_OTHEROBJECT but is overridden by several
80	* subclasses such as VirtualBox, Host, Machine and others.
81	*
82	* On the first call this method lazily creates the RWLockHandle.
83	*
84	* @return
85	*/
86	/* virtual */
87	RWLockHandle *VirtualBoxBase::lockHandle() const
88	{
89	/* lazy initialization */
90	if (RT_UNLIKELY(!mObjectLock))
91	{
92	AssertCompile (sizeof (RWLockHandle ) == sizeof (void ));
93
94	// locking class is LOCKCLASS_VIRTUALBOXOBJECT for the VirtualBox singleton,
95	// LOCKCLASS_HOSTOBJECT for the Host object and LOCKCLASS_OBJECT for any other object
96	RWLockHandle *objLock = new RWLockHandle(getLockingClass());
97	if (!ASMAtomicCmpXchgPtr ((void * volatile *) &mObjectLock, objLock, NULL))
98	{
99	delete objLock;
100	objLock = (RWLockHandle ) ASMAtomicReadPtr ((void volatile *) &mObjectLock);
101	}
102	return objLock;
103	}
104	return mObjectLock;
105	}
106
107	/**
108	* Increments the number of calls to this object by one.
109	*
110	* After this method succeeds, it is guaranted that the object will remain
111	* in the Ready (or in the Limited) state at least until #releaseCaller() is
112	* called.
113	*
114	* This method is intended to mark the beginning of sections of code within
115	* methods of COM objects that depend on the readiness (Ready) state. The
116	* Ready state is a primary "ready to serve" state. Usually all code that
117	* works with component's data depends on it. On practice, this means that
118	* almost every public method, setter or getter of the object should add
119	* itself as an object's caller at the very beginning, to protect from an
120	* unexpected uninitialization that may happen on a different thread.
121	*
122	* Besides the Ready state denoting that the object is fully functional,
123	* there is a special Limited state. The Limited state means that the object
124	* is still functional, but its functionality is limited to some degree, so
125	* not all operations are possible. The @a aLimited argument to this method
126	* determines whether the caller represents this limited functionality or
127	* not.
128	*
129	* This method succeeeds (and increments the number of callers) only if the
130	* current object's state is Ready. Otherwise, it will return E_ACCESSDENIED
131	* to indicate that the object is not operational. There are two exceptions
132	* from this rule:
133	* <ol>
134	* <li>If the @a aLimited argument is \|true\|, then this method will also
135	* succeeed if the object's state is Limited (or Ready, of course).
136	* </li>
137	* <li>If this method is called from the same thread that placed
138	* the object to InInit or InUninit state (i.e. either from within the
139	* AutoInitSpan or AutoUninitSpan scope), it will succeed as well (but
140	* will not increase the number of callers).
141	* </li>
142	* </ol>
143	*
144	* Normally, calling addCaller() never blocks. However, if this method is
145	* called by a thread created from within the AutoInitSpan scope and this
146	* scope is still active (i.e. the object state is InInit), it will block
147	* until the AutoInitSpan destructor signals that it has finished
148	* initialization.
149	*
150	* Also, addCaller() will block if the object is probing uninitialization on
151	* another thread with AutoMayUninitSpan (i.e. the object state is MayUninit).
152	* And again, the block will last until the AutoMayUninitSpan destructor signals
153	* that it has finished probing and the object is either ready again or will
154	* uninitialize shortly (so that addCaller() will fail).
155	*
156	* When this method returns a failure, the caller must not use the object
157	* and should return the failed result code to its own caller.
158	*
159	* @param aState Where to store the current object's state (can be
160	* used in overriden methods to determine the cause of
161	* the failure).
162	* @param aLimited \|true\| to add a limited caller.
163	*
164	* @return S_OK on success or E_ACCESSDENIED on failure.
165	*
166	* @note It is preferrable to use the #addLimitedCaller() rather than
167	* calling this method with @a aLimited = \|true\|, for better
168	* self-descriptiveness.
169	*
170	* @sa #addLimitedCaller()
171	* @sa #releaseCaller()
172	*/
173	HRESULT VirtualBoxBase::addCaller(State aState / = NULL */,
174	bool aLimited /* = false */)
175	{
176	AutoWriteLock stateLock(mStateLock COMMA_LOCKVAL_SRC_POS);
177
178	HRESULT rc = E_ACCESSDENIED;
179
180	if (mState == Ready \|\| (aLimited && mState == Limited))
181	{
182	/* if Ready or allows Limited, increase the number of callers */
183	++ mCallers;
184	rc = S_OK;
185	}
186	else
187	if (mState == InInit \|\| mState == MayUninit \|\| mState == InUninit)
188	{
189	if (mStateChangeThread == RTThreadSelf())
190	{
191	/* Called from the same thread that is doing AutoInitSpan or
192	* AutoUninitSpan or AutoMayUninitSpan, just succeed */
193	rc = S_OK;
194	}
195	else if (mState == InInit \|\| mState == MayUninit)
196	{
197	/* One of the two:
198	*
199	* 1) addCaller() is called by a "child" thread while the "parent"
200	* thread is still doing AutoInitSpan/AutoReinitSpan, so wait for
201	* the state to become either Ready/Limited or InitFailed (in
202	* case of init failure).
203	*
204	* 2) addCaller() is called while another thread is in
205	* AutoMayUninitSpan, so wait for the state to become either
206	* Ready or WillUninit.
207	*
208	* Note that in either case we increase the number of callers anyway
209	* -- to prevent AutoUninitSpan from early completion if we are
210	* still not scheduled to pick up the posted semaphore when uninit()
211	* is called.
212	*/
213	++ mCallers;
214
215	/* lazy semaphore creation */
216	if (mInitUninitSem == NIL_RTSEMEVENTMULTI)
217	{
218	RTSemEventMultiCreate (&mInitUninitSem);
219	Assert (mInitUninitWaiters == 0);
220	}
221
222	++ mInitUninitWaiters;
223
224	LogFlowThisFunc((mState == InInit ?
225	"Waiting for AutoInitSpan/AutoReinitSpan to "
226	"finish...\n" :
227	"Waiting for AutoMayUninitSpan to finish...\n"));
228
229	stateLock.leave();
230	RTSemEventMultiWait (mInitUninitSem, RT_INDEFINITE_WAIT);
231	stateLock.enter();
232
233	if (-- mInitUninitWaiters == 0)
234	{
235	/* destroy the semaphore since no more necessary */
236	RTSemEventMultiDestroy (mInitUninitSem);
237	mInitUninitSem = NIL_RTSEMEVENTMULTI;
238	}
239
240	if (mState == Ready \|\| (aLimited && mState == Limited))
241	rc = S_OK;
242	else
243	{
244	Assert (mCallers != 0);
245	-- mCallers;
246	if (mCallers == 0 && mState == InUninit)
247	{
248	/* inform AutoUninitSpan ctor there are no more callers */
249	RTSemEventSignal (mZeroCallersSem);
250	}
251	}
252	}
253	}
254
255	if (aState)
256	*aState = mState;
257
258	return rc;
259	}
260
261	/**
262	* Decreases the number of calls to this object by one.
263	*
264	* Must be called after every #addCaller() or #addLimitedCaller() when
265	* protecting the object from uninitialization is no more necessary.
266	*/
267	void VirtualBoxBase::releaseCaller()
268	{
269	AutoWriteLock stateLock(mStateLock COMMA_LOCKVAL_SRC_POS);
270
271	if (mState == Ready \|\| mState == Limited)
272	{
273	/* if Ready or Limited, decrease the number of callers */
274	AssertMsgReturn (mCallers != 0, ("mCallers is ZERO!"), (void) 0);
275	-- mCallers;
276
277	return;
278	}
279
280	if (mState == InInit \|\| mState == MayUninit \|\| mState == InUninit)
281	{
282	if (mStateChangeThread == RTThreadSelf())
283	{
284	/* Called from the same thread that is doing AutoInitSpan,
285	* AutoMayUninitSpan or AutoUninitSpan: just succeed */
286	return;
287	}
288
289	if (mState == MayUninit \|\| mState == InUninit)
290	{
291	/* the caller is being released after AutoUninitSpan or
292	* AutoMayUninitSpan has begun */
293	AssertMsgReturn (mCallers != 0, ("mCallers is ZERO!"), (void) 0);
294	-- mCallers;
295
296	if (mCallers == 0)
297	{
298	/* inform the AutoUninitSpan ctor there are no more callers /
299	RTSemEventSignal (mZeroCallersSem);
300	}
301
302	return;
303	}
304	}
305
306	AssertMsgFailed (("mState = %d!", mState));
307	}
308
309	////////////////////////////////////////////////////////////////////////////////
310	//
311	// AutoInitSpan methods
312	//
313	////////////////////////////////////////////////////////////////////////////////
314
315	/**
316	* Creates a smart initialization span object that places the object to
317	* InInit state.
318	*
319	* Please see the AutoInitSpan class description for more info.
320	*
321	* @param aObj \|this\| pointer of the managed VirtualBoxBase object whose
322	* init() method is being called.
323	* @param aResult Default initialization result.
324	*/
325	AutoInitSpan::AutoInitSpan(VirtualBoxBase *aObj,
326	Result aResult /* = Failed */)
327	: mObj(aObj),
328	mResult(aResult),
329	mOk(false)
330	{
331	Assert(aObj);
332
333	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
334
335	mOk = mObj->mState == VirtualBoxBase::NotReady;
336	AssertReturnVoid (mOk);
337
338	mObj->setState(VirtualBoxBase::InInit);
339	}
340
341	/**
342	* Places the managed VirtualBoxBase object to Ready/Limited state if the
343	* initialization succeeded or partly succeeded, or places it to InitFailed
344	* state and calls the object's uninit() method.
345	*
346	* Please see the AutoInitSpan class description for more info.
347	*/
348	AutoInitSpan::~AutoInitSpan()
349	{
350	/* if the state was other than NotReady, do nothing */
351	if (!mOk)
352	return;
353
354	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
355
356	Assert(mObj->mState == VirtualBoxBase::InInit);
357
358	if (mObj->mCallers > 0)
359	{
360	Assert(mObj->mInitUninitWaiters > 0);
361
362	/* We have some pending addCaller() calls on other threads (created
363	* during InInit), signal that InInit is finished and they may go on. */
364	RTSemEventMultiSignal(mObj->mInitUninitSem);
365	}
366
367	if (mResult == Succeeded)
368	{
369	mObj->setState(VirtualBoxBase::Ready);
370	}
371	else
372	if (mResult == Limited)
373	{
374	mObj->setState(VirtualBoxBase::Limited);
375	}
376	else
377	{
378	mObj->setState(VirtualBoxBase::InitFailed);
379	/* leave the lock to prevent nesting when uninit() is called */
380	stateLock.leave();
381	/* call uninit() to let the object uninit itself after failed init() */
382	mObj->uninit();
383	/* Note: the object may no longer exist here (for example, it can call
384	* the destructor in uninit()) */
385	}
386	}
387
388	// AutoReinitSpan methods
389	////////////////////////////////////////////////////////////////////////////////
390
391	/**
392	* Creates a smart re-initialization span object and places the object to
393	* InInit state.
394	*
395	* Please see the AutoInitSpan class description for more info.
396	*
397	* @param aObj \|this\| pointer of the managed VirtualBoxBase object whose
398	* re-initialization method is being called.
399	*/
400	AutoReinitSpan::AutoReinitSpan(VirtualBoxBase *aObj)
401	: mObj(aObj),
402	mSucceeded(false),
403	mOk(false)
404	{
405	Assert(aObj);
406
407	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
408
409	mOk = mObj->mState == VirtualBoxBase::Limited;
410	AssertReturnVoid (mOk);
411
412	mObj->setState(VirtualBoxBase::InInit);
413	}
414
415	/**
416	* Places the managed VirtualBoxBase object to Ready state if the
417	* re-initialization succeeded (i.e. #setSucceeded() has been called) or back to
418	* Limited state otherwise.
419	*
420	* Please see the AutoInitSpan class description for more info.
421	*/
422	AutoReinitSpan::~AutoReinitSpan()
423	{
424	/* if the state was other than Limited, do nothing */
425	if (!mOk)
426	return;
427
428	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
429
430	Assert(mObj->mState == VirtualBoxBase::InInit);
431
432	if (mObj->mCallers > 0 && mObj->mInitUninitWaiters > 0)
433	{
434	/* We have some pending addCaller() calls on other threads (created
435	* during InInit), signal that InInit is finished and they may go on. */
436	RTSemEventMultiSignal(mObj->mInitUninitSem);
437	}
438
439	if (mSucceeded)
440	{
441	mObj->setState(VirtualBoxBase::Ready);
442	}
443	else
444	{
445	mObj->setState(VirtualBoxBase::Limited);
446	}
447	}
448
449	// AutoUninitSpan methods
450	////////////////////////////////////////////////////////////////////////////////
451
452	/**
453	* Creates a smart uninitialization span object and places this object to
454	* InUninit state.
455	*
456	* Please see the AutoInitSpan class description for more info.
457	*
458	* @note This method blocks the current thread execution until the number of
459	* callers of the managed VirtualBoxBase object drops to zero!
460	*
461	* @param aObj \|this\| pointer of the VirtualBoxBase object whose uninit()
462	* method is being called.
463	*/
464	AutoUninitSpan::AutoUninitSpan(VirtualBoxBase *aObj)
465	: mObj(aObj),
466	mInitFailed(false),
467	mUninitDone(false)
468	{
469	Assert(aObj);
470
471	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
472
473	Assert(mObj->mState != VirtualBoxBase::InInit);
474
475	/* Set mUninitDone to \|true\| if this object is already uninitialized
476	* (NotReady) or if another AutoUninitSpan is currently active on some
477	* other thread (InUninit). */
478	mUninitDone = mObj->mState == VirtualBoxBase::NotReady
479	\|\| mObj->mState == VirtualBoxBase::InUninit;
480
481	if (mObj->mState == VirtualBoxBase::InitFailed)
482	{
483	/* we've been called by init() on failure */
484	mInitFailed = true;
485	}
486	else
487	{
488	if (mUninitDone)
489	{
490	/* do nothing if already uninitialized */
491	if (mObj->mState == VirtualBoxBase::NotReady)
492	return;
493
494	/* otherwise, wait until another thread finishes uninitialization.
495	* This is necessary to make sure that when this method returns, the
496	* object is NotReady and therefore can be deleted (for example).
497	* In particular, this is used by
498	* VirtualBoxBaseWithTypedChildrenNEXT::uninitDependentChildren(). */
499
500	/* lazy semaphore creation */
501	if (mObj->mInitUninitSem == NIL_RTSEMEVENTMULTI)
502	{
503	RTSemEventMultiCreate(&mObj->mInitUninitSem);
504	Assert(mObj->mInitUninitWaiters == 0);
505	}
506	++mObj->mInitUninitWaiters;
507
508	LogFlowFunc(("{%p}: Waiting for AutoUninitSpan to finish...\n",
509	mObj));
510
511	stateLock.leave();
512	RTSemEventMultiWait(mObj->mInitUninitSem, RT_INDEFINITE_WAIT);
513	stateLock.enter();
514
515	if (--mObj->mInitUninitWaiters == 0)
516	{
517	/* destroy the semaphore since no more necessary */
518	RTSemEventMultiDestroy(mObj->mInitUninitSem);
519	mObj->mInitUninitSem = NIL_RTSEMEVENTMULTI;
520	}
521
522	return;
523	}
524	}
525
526	/* go to InUninit to prevent from adding new callers */
527	mObj->setState(VirtualBoxBase::InUninit);
528
529	/* wait for already existing callers to drop to zero */
530	if (mObj->mCallers > 0)
531	{
532	/* lazy creation */
533	Assert(mObj->mZeroCallersSem == NIL_RTSEMEVENT);
534	RTSemEventCreate(&mObj->mZeroCallersSem);
535
536	/* wait until remaining callers release the object */
537	LogFlowFunc(("{%p}: Waiting for callers (%d) to drop to zero...\n",
538	mObj, mObj->mCallers));
539
540	stateLock.leave();
541	RTSemEventWait(mObj->mZeroCallersSem, RT_INDEFINITE_WAIT);
542	}
543	}
544
545	/**
546	* Places the managed VirtualBoxBase object to the NotReady state.
547	*/
548	AutoUninitSpan::~AutoUninitSpan()
549	{
550	/* do nothing if already uninitialized */
551	if (mUninitDone)
552	return;
553
554	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
555
556	Assert(mObj->mState == VirtualBoxBase::InUninit);
557
558	mObj->setState(VirtualBoxBase::NotReady);
559	}
560
561	// AutoMayUninitSpan methods
562	////////////////////////////////////////////////////////////////////////////////
563
564	/**
565	* Creates a smart initialization span object that places the object to
566	* MayUninit state.
567	*
568	* Please see the AutoMayUninitSpan class description for more info.
569	*
570	* @param aObj \|this\| pointer of the managed VirtualBoxBase object whose
571	* uninit() method to be probably called.
572	*/
573	AutoMayUninitSpan::AutoMayUninitSpan(VirtualBoxBase *aObj)
574	: mObj(aObj),
575	mRC(E_FAIL),
576	mAlreadyInProgress(false),
577	mAcceptUninit (false)
578	{
579	Assert(aObj);
580
581	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
582
583	AssertReturnVoid( mObj->mState != VirtualBoxBase::InInit
584	&& mObj->mState != VirtualBoxBase::InUninit);
585
586	switch (mObj->mState)
587	{
588	case VirtualBoxBase::Ready:
589	break;
590	case VirtualBoxBase::MayUninit:
591	/* Nothing to be done if already in MayUninit. */
592	mAlreadyInProgress = true;
593	mRC = S_OK;
594	return;
595	default:
596	/* Abuse mObj->addCaller() to get the extended error info possibly
597	* set by reimplementations of addCaller() and return it to the
598	* caller. Note that this abuse is supposed to be safe because we
599	* should've filtered out all states where addCaller() would do
600	* something else but set error info. */
601	mRC = mObj->addCaller();
602	Assert(FAILED (mRC));
603	return;
604	}
605
606	/* go to MayUninit to cause new callers to wait until we finish */
607	mObj->setState(VirtualBoxBase::MayUninit);
608	mRC = S_OK;
609
610	/* wait for already existing callers to drop to zero */
611	if (mObj->mCallers > 0)
612	{
613	/* lazy creation */
614	Assert(mObj->mZeroCallersSem == NIL_RTSEMEVENT);
615	RTSemEventCreate(&mObj->mZeroCallersSem);
616
617	/* wait until remaining callers release the object */
618	LogFlowFunc(("{%p}: Waiting for callers (%d) to drop to zero...\n",
619	mObj, mObj->mCallers));
620
621	stateLock.leave();
622	RTSemEventWait(mObj->mZeroCallersSem, RT_INDEFINITE_WAIT);
623	}
624	}
625
626	/**
627	* Places the managed VirtualBoxBase object back to Ready state if
628	* #acceptUninit() was not called, or places it to WillUninit state and calls
629	* the object's uninit() method.
630	*
631	* Please see the AutoMayUninitSpan class description for more info.
632	*/
633	AutoMayUninitSpan::~AutoMayUninitSpan()
634	{
635	/* if we did nothing in the constructor, do nothing here */
636	if (mAlreadyInProgress \|\| FAILED (mRC))
637	return;
638
639	AutoWriteLock stateLock(mObj->mStateLock COMMA_LOCKVAL_SRC_POS);
640
641	Assert(mObj->mState == VirtualBoxBase::MayUninit);
642
643	if (mObj->mCallers > 0)
644	{
645	Assert(mObj->mInitUninitWaiters > 0);
646
647	/* We have some pending addCaller() calls on other threads made after
648	* going to during MayUnit, signal that MayUnit is finished and they may
649	* go on. */
650	RTSemEventMultiSignal(mObj->mInitUninitSem);
651	}
652
653	if (!mAcceptUninit)
654	{
655	mObj->setState(VirtualBoxBase::Ready);
656	}
657	else
658	{
659	mObj->setState(VirtualBoxBase::WillUninit);
660	/* leave the lock to prevent nesting when uninit() is called */
661	stateLock.leave();
662	/* call uninit() to let the object uninit itself */
663	mObj->uninit();
664	/* Note: the object may no longer exist here (for example, it can call
665	* the destructor in uninit()) */
666	}
667	}
668
669	////////////////////////////////////////////////////////////////////////////////
670	//
671	// VirtualBoxBase
672	//
673	////////////////////////////////////////////////////////////////////////////////
674
675	/**
676	* Translates the given text string according to the currently installed
677	* translation table and current context. The current context is determined
678	* by the context parameter. Additionally, a comment to the source text
679	* string text can be given. This comment (which is NULL by default)
680	* is helpful in situations where it is necessary to distinguish between
681	* two or more semantically different roles of the same source text in the
682	* same context.
683	*
684	* @param context the context of the translation (can be NULL
685	* to indicate the global context)
686	* @param sourceText the string to translate
687	* @param comment the comment to the string (NULL means no comment)
688	*
689	* @return
690	* the translated version of the source string in UTF-8 encoding,
691	* or the source string itself if the translation is not found
692	* in the given context.
693	*/
694	// static
695	const char VirtualBoxBase::translate (const char /* context /, const char sourceText,
696	const char * /* comment */)
697	{
698	#if 0
699	Log(("VirtualBoxBase::translate:\n"
700	" context={%s}\n"
701	" sourceT={%s}\n"
702	" comment={%s}\n",
703	context, sourceText, comment));
704	#endif
705
706	/// @todo (dmik) incorporate Qt translation file parsing and lookup
707	return sourceText;
708	}
709
710	////////////////////////////////////////////////////////////////////////////////
711	//
712	// VirtualBoxSupportTranslationBase
713	//
714	////////////////////////////////////////////////////////////////////////////////
715
716	/**
717	* Modifies the given argument so that it will contain only a class name
718	* (null-terminated). The argument must point to a <b>non-constant</b>
719	* string containing a valid value, as it is generated by the
720	* __PRETTY_FUNCTION__ built-in macro of the GCC compiler, or by the
721	* __FUNCTION__ macro of any other compiler.
722	*
723	* The function assumes that the macro is used within the member of the
724	* class derived from the VirtualBoxSupportTranslation<> template.
725	*
726	* @param prettyFunctionName string to modify
727	* @return
728	* true on success and false otherwise
729	*/
730	bool VirtualBoxSupportTranslationBase::cutClassNameFrom__PRETTY_FUNCTION__ (char *fn)
731	{
732	Assert (fn);
733	if (!fn)
734	return false;
735
736	#if defined (__GNUC__)
737
738	// the format is like:
739	// VirtualBoxSupportTranslation<C>::VirtualBoxSupportTranslation() [with C = VirtualBox]
740
741	#define START " = "
742	#define END "]"
743
744	#elif defined (_MSC_VER)
745
746	// the format is like:
747	// VirtualBoxSupportTranslation<class VirtualBox>::__ctor
748
749	#define START "<class "
750	#define END ">::"
751
752	#endif
753
754	char *start = strstr (fn, START);
755	Assert (start);
756	if (start)
757	{
758	start += sizeof (START) - 1;
759	char *end = strstr (start, END);
760	Assert (end && (end > start));
761	if (end && (end > start))
762	{
763	size_t len = end - start;
764	memmove (fn, start, len);
765	fn [len] = 0;
766	return true;
767	}
768	}
769
770	#undef END
771	#undef START
772
773	return false;
774	}
775
776	////////////////////////////////////////////////////////////////////////////////
777	//
778	// VirtualBoxSupportErrorInfoImplBase
779	//
780	////////////////////////////////////////////////////////////////////////////////
781
782	RTTLS VirtualBoxSupportErrorInfoImplBase::MultiResult::sCounter = NIL_RTTLS;
783
784	void VirtualBoxSupportErrorInfoImplBase::MultiResult::init()
785	{
786	if (sCounter == NIL_RTTLS)
787	{
788	sCounter = RTTlsAlloc();
789	AssertReturnVoid (sCounter != NIL_RTTLS);
790	}
791
792	uintptr_t counter = (uintptr_t) RTTlsGet (sCounter);
793	++ counter;
794	RTTlsSet (sCounter, (void *) counter);
795	}
796
797	VirtualBoxSupportErrorInfoImplBase::MultiResult::~MultiResult()
798	{
799	uintptr_t counter = (uintptr_t) RTTlsGet (sCounter);
800	AssertReturnVoid (counter != 0);
801	-- counter;
802	RTTlsSet (sCounter, (void *) counter);
803	}
804
805	/**
806	* Sets error info for the current thread. This is an internal function that
807	* gets eventually called by all public variants. If @a aWarning is
808	* @c true, then the highest (31) bit in the @a aResultCode value which
809	* indicates the error severity is reset to zero to make sure the receiver will
810	* recognize that the created error info object represents a warning rather
811	* than an error.
812	*/
813	/* static */
814	HRESULT VirtualBoxSupportErrorInfoImplBase::setErrorInternal (
815	HRESULT aResultCode, const GUID &aIID,
816	const Bstr &aComponent, const Bstr &aText,
817	bool aWarning, bool aLogIt)
818	{
819	/* whether multi-error mode is turned on */
820	bool preserve = ((uintptr_t) RTTlsGet (MultiResult::sCounter)) > 0;
821
822	if (aLogIt)
823	LogRel (("ERROR [COM]: aRC=%Rhrc (%#08x) aIID={%RTuuid} aComponent={%ls} aText={%ls} "
824	"aWarning=%RTbool, preserve=%RTbool\n",
825	aResultCode, aResultCode, &aIID, aComponent.raw(), aText.raw(), aWarning,
826	preserve));
827
828	/* these are mandatory, others -- not */
829	AssertReturn((!aWarning && FAILED (aResultCode)) \|\|
830	(aWarning && aResultCode != S_OK),
831	E_FAIL);
832	AssertReturn(!aText.isEmpty(), E_FAIL);
833
834	/* reset the error severity bit if it's a warning */
835	if (aWarning)
836	aResultCode &= ~0x80000000;
837
838	HRESULT rc = S_OK;
839
840	do
841	{
842	ComObjPtr<VirtualBoxErrorInfo> info;
843	rc = info.createObject();
844	if (FAILED(rc)) break;
845
846	#if !defined (VBOX_WITH_XPCOM)
847
848	ComPtr<IVirtualBoxErrorInfo> curInfo;
849	if (preserve)
850	{
851	/* get the current error info if any */
852	ComPtr<IErrorInfo> err;
853	rc = ::GetErrorInfo (0, err.asOutParam());
854	if (FAILED(rc)) break;
855	rc = err.queryInterfaceTo(curInfo.asOutParam());
856	if (FAILED (rc))
857	{
858	/* create a IVirtualBoxErrorInfo wrapper for the native
859	* IErrorInfo object */
860	ComObjPtr<VirtualBoxErrorInfo> wrapper;
861	rc = wrapper.createObject();
862	if (SUCCEEDED(rc))
863	{
864	rc = wrapper->init (err);
865	if (SUCCEEDED(rc))
866	curInfo = wrapper;
867	}
868	}
869	}
870	/* On failure, curInfo will stay null */
871	Assert (SUCCEEDED(rc) \|\| curInfo.isNull());
872
873	/* set the current error info and preserve the previous one if any */
874	rc = info->init (aResultCode, aIID, aComponent, aText, curInfo);
875	if (FAILED(rc)) break;
876
877	ComPtr<IErrorInfo> err;
878	rc = info.queryInterfaceTo(err.asOutParam());
879	if (SUCCEEDED(rc))
880	rc = ::SetErrorInfo (0, err);
881
882	#else // !defined (VBOX_WITH_XPCOM)
883
884	nsCOMPtr <nsIExceptionService> es;
885	es = do_GetService (NS_EXCEPTIONSERVICE_CONTRACTID, &rc);
886	if (NS_SUCCEEDED(rc))
887	{
888	nsCOMPtr <nsIExceptionManager> em;
889	rc = es->GetCurrentExceptionManager (getter_AddRefs (em));
890	if (FAILED(rc)) break;
891
892	ComPtr<IVirtualBoxErrorInfo> curInfo;
893	if (preserve)
894	{
895	/* get the current error info if any */
896	ComPtr<nsIException> ex;
897	rc = em->GetCurrentException (ex.asOutParam());
898	if (FAILED(rc)) break;
899	rc = ex.queryInterfaceTo(curInfo.asOutParam());
900	if (FAILED(rc))
901	{
902	/* create a IVirtualBoxErrorInfo wrapper for the native
903	* nsIException object */
904	ComObjPtr<VirtualBoxErrorInfo> wrapper;
905	rc = wrapper.createObject();
906	if (SUCCEEDED(rc))
907	{
908	rc = wrapper->init (ex);
909	if (SUCCEEDED(rc))
910	curInfo = wrapper;
911	}
912	}
913	}
914	/* On failure, curInfo will stay null */
915	Assert (SUCCEEDED(rc) \|\| curInfo.isNull());
916
917	/* set the current error info and preserve the previous one if any */
918	rc = info->init (aResultCode, aIID, aComponent, aText, curInfo);
919	if (FAILED(rc)) break;
920
921	ComPtr<nsIException> ex;
922	rc = info.queryInterfaceTo(ex.asOutParam());
923	if (SUCCEEDED(rc))
924	rc = em->SetCurrentException (ex);
925	}
926	else if (rc == NS_ERROR_UNEXPECTED)
927	{
928	/*
929	* It is possible that setError() is being called by the object
930	* after the XPCOM shutdown sequence has been initiated
931	* (for example, when XPCOM releases all instances it internally
932	* references, which can cause object's FinalConstruct() and then
933	* uninit()). In this case, do_GetService() above will return
934	* NS_ERROR_UNEXPECTED and it doesn't actually make sense to
935	* set the exception (nobody will be able to read it).
936	*/
937	LogWarningFunc (("Will not set an exception because "
938	"nsIExceptionService is not available "
939	"(NS_ERROR_UNEXPECTED). "
940	"XPCOM is being shutdown?\n"));
941	rc = NS_OK;
942	}
943
944	#endif // !defined (VBOX_WITH_XPCOM)
945	}
946	while (0);
947
948	AssertComRC (rc);
949
950	return SUCCEEDED(rc) ? aResultCode : rc;
951	}
952
953
954	/**
955	* Uninitializes all dependent children registered on this object with
956	* #addDependentChild().
957	*
958	* Must be called from within the AutoUninitSpan (i.e.
959	* typically from this object's uninit() method) to uninitialize children
960	* before this object goes out of service and becomes unusable.
961	*
962	* Note that this method will call uninit() methods of child objects. If
963	* these methods need to call the parent object during uninitialization,
964	* #uninitDependentChildren() must be called before the relevant part of the
965	* parent is uninitialized: usually at the begnning of the parent
966	* uninitialization sequence.
967	*
968	* Keep in mind that the uninitialized child objects may be no longer available
969	* (i.e. may be deleted) after this method returns.
970	*
971	* @note Locks #childrenLock() for writing.
972	*
973	* @note May lock something else through the called children.
974	*/
975	void VirtualBoxBaseWithChildrenNEXT::uninitDependentChildren()
976	{
977	AutoCaller autoCaller(this);
978
979	/* sanity */
980	AssertReturnVoid (autoCaller.state() == InUninit \|\|
981	autoCaller.state() == InInit);
982
983	AutoWriteLock chLock(childrenLock() COMMA_LOCKVAL_SRC_POS);
984
985	size_t count = mDependentChildren.size();
986
987	while (count != 0)
988	{
989	/* strongly reference the weak child from the map to make sure it won't
990	* be deleted while we've released the lock */
991	DependentChildren::iterator it = mDependentChildren.begin();
992	ComPtr<IUnknown> unk = it->first;
993	Assert (!unk.isNull());
994
995	VirtualBoxBase *child = it->second;
996
997	/* release the lock to let children stuck in removeDependentChild() go
998	* on (otherwise we'll deadlock in uninit() */
999	chLock.leave();
1000
1001	/* Note that if child->uninit() happens to be called on another
1002	* thread right before us and is not yet finished, the second
1003	* uninit() call will wait until the first one has done so
1004	* (thanks to AutoUninitSpan). */
1005	Assert (child);
1006	if (child)
1007	child->uninit();
1008
1009	chLock.enter();
1010
1011	/* uninit() is guaranteed to be done here so the child must be already
1012	* deleted from the list by removeDependentChild() called from there.
1013	* Do some checks to avoid endless loops when the user is forgetful */
1014	-- count;
1015	Assert (count == mDependentChildren.size());
1016	if (count != mDependentChildren.size())
1017	mDependentChildren.erase (it);
1018
1019	Assert (count == mDependentChildren.size());
1020	}
1021	}
1022
1023	/**
1024	* Returns a pointer to the dependent child (registered using
1025	* #addDependentChild()) corresponding to the given interface pointer or NULL if
1026	* the given pointer is unrelated.
1027	*
1028	* The relation is checked by using the given interface pointer as a key in the
1029	* map of dependent children.
1030	*
1031	* Note that ComPtr<IUnknown> is used as an argument instead of IUnknown * in
1032	* order to guarantee IUnknown identity and disambiguation by doing
1033	* QueryInterface (IUnknown) rather than a regular C cast.
1034	*
1035	* @param aUnk Pointer to map to the dependent child object.
1036	* @return Pointer to the dependent VirtualBoxBase child object.
1037	*
1038	* @note Locks #childrenLock() for reading.
1039	*/
1040	VirtualBoxBase* VirtualBoxBaseWithChildrenNEXT::getDependentChild(const ComPtr<IUnknown> &aUnk)
1041	{
1042	AssertReturn(!aUnk.isNull(), NULL);
1043
1044	AutoCaller autoCaller(this);
1045
1046	/* return NULL if uninitDependentChildren() is in action */
1047	if (autoCaller.state() == InUninit)
1048	return NULL;
1049
1050	AutoReadLock alock(childrenLock() COMMA_LOCKVAL_SRC_POS);
1051
1052	DependentChildren::const_iterator it = mDependentChildren.find (aUnk);
1053	if (it == mDependentChildren.end())
1054	return NULL;
1055
1056	return (*it).second;
1057	}
1058
1059	/** Helper for addDependentChild(). */
1060	void VirtualBoxBaseWithChildrenNEXT::doAddDependentChild(IUnknown *aUnk,
1061	VirtualBoxBase *aChild)
1062	{
1063	AssertReturnVoid (aUnk != NULL);
1064	AssertReturnVoid (aChild != NULL);
1065
1066	AutoCaller autoCaller(this);
1067
1068	/* sanity */
1069	AssertReturnVoid (autoCaller.state() == InInit \|\|
1070	autoCaller.state() == Ready \|\|
1071	autoCaller.state() == Limited);
1072
1073	AutoWriteLock alock(childrenLock() COMMA_LOCKVAL_SRC_POS);
1074
1075	std::pair <DependentChildren::iterator, bool> result =
1076	mDependentChildren.insert (DependentChildren::value_type (aUnk, aChild));
1077	AssertMsg (result.second, ("Failed to insert child %p to the map\n", aUnk));
1078	}
1079
1080	/** Helper for removeDependentChild(). */
1081	void VirtualBoxBaseWithChildrenNEXT::doRemoveDependentChild (IUnknown *aUnk)
1082	{
1083	AssertReturnVoid (aUnk);
1084
1085	AutoCaller autoCaller(this);
1086
1087	/* sanity */
1088	AssertReturnVoid (autoCaller.state() == InUninit \|\|
1089	autoCaller.state() == InInit \|\|
1090	autoCaller.state() == Ready \|\|
1091	autoCaller.state() == Limited);
1092
1093	AutoWriteLock alock(childrenLock() COMMA_LOCKVAL_SRC_POS);
1094
1095	DependentChildren::size_type result = mDependentChildren.erase (aUnk);
1096	AssertMsg (result == 1, ("Failed to remove child %p from the map\n", aUnk));
1097	NOREF (result);
1098	}
1099
1100	/* vi: set tabstop=4 shiftwidth=4 expandtab: */

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Main/VirtualBoxBase.cpp@ 25881

Download in other formats: