EventImpl.cpp revision c2590a722c15520a45551ed7dc02d4831fb1a48e
/* $Id$ */
/** @file
* VirtualBox COM Event class implementation
*/
/*
* Copyright (C) 2010-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.
*/
/** @page pg_main_events Events
*
* Theory of operations.
*
* This code implements easily extensible event mechanism, letting us
* to make any VirtualBox object an event source (by aggregating an EventSource instance).
* Another entity could subscribe to the event source for events it is interested in.
* If an event is waitable, it's possible to wait until all listeners
* registered at the moment of firing event as ones interested in this
* event acknowledged that they finished event processing (thus allowing
* vetoable events).
*
* Listeners can be registered as active or passive ones, defining policy of delivery.
* For *active* listeners, their HandleEvent() method is invoked when event is fired by
* the event source (pretty much callbacks).
* For *passive* listeners, it's up to an event consumer to perform GetEvent() operation
* with given listener, and then perform desired operation with returned event, if any.
* For passive listeners case, listener instance serves as merely a key referring to
* particular event consumer, thus HandleEvent() implementation isn't that important.
* IEventSource's CreateListener() could be used to create such a listener.
* Passive mode is designed for transports not allowing callbacks, such as webservices
* running on top of HTTP, and for situations where consumer wants exact control on
* context where event handler is executed (such as GUI thread for some toolkits).
*
* Internal EventSource data structures are optimized for fast event delivery, while
* listener registration/unregistration operations are expected being pretty rare.
* Passive mode listeners keep an internal event queue for all events they receive,
* and all waitable events are added to the pending events map. This map keeps track
* of how many listeners are still not acknowledged their event, and once this counter
* reach zero, element is removed from pending events map, and event is marked as processed.
* Thus if passive listener's user forgets to call IEventSource's EventProcessed()
* waiters may never know that event processing finished.
*/
#include <list>
#include <map>
#include <deque>
#include "EventImpl.h"
#include "AutoCaller.h"
#include "Logging.h"
#include <iprt/semaphore.h>
#include <iprt/critsect.h>
class ListenerRecord;
{
Data()
{}
};
{
m = new Data;
return BaseFinalConstruct();
}
void VBoxEvent::FinalRelease()
{
if (m)
{
uninit();
delete m;
m = 0;
}
}
{
AutoInitSpan autoInitSpan(this);
m->mProcessed = !aWaitable;
do {
if (aWaitable)
{
if (RT_FAILURE(vrc))
{
AssertFailed();
}
}
} while (0);
/* Confirm a successful initialization */
return rc;
}
{
if (!m)
return;
m->mProcessed = TRUE;
m->mType = VBoxEventType_Invalid;
if (m->mWaitEvent != NIL_RTSEMEVENT)
{
::RTSemEventDestroy(m->mWaitEvent);
m->mWaitEvent = NIL_RTSEMEVENT;
}
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
// never changes while event alive, no locking
return S_OK;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
return S_OK;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
// never changes while event alive, no locking
return S_OK;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
if (m->mProcessed)
return S_OK;
m->mProcessed = TRUE;
// notify waiters
::RTSemEventSignal(m->mWaitEvent);
return S_OK;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
{
if (m->mProcessed)
{
return S_OK;
}
if (aTimeout == 0)
{
*aResult = m->mProcessed;
return S_OK;
}
}
/* @todo: maybe while loop for spurious wakeups? */
("RTSemEventWait returned %Rrc\n", vrc));
if (RT_SUCCESS(vrc))
{
AssertMsg(m->mProcessed,
("mProcessed must be set here\n"));
*aResult = m->mProcessed;
}
else
{
}
return S_OK;
}
struct VBoxVetoEvent::Data
{
Data() :
{}
};
{
m = new Data;
return S_OK;
}
void VBoxVetoEvent::FinalRelease()
{
if (m)
{
uninit();
delete m;
m = 0;
}
}
{
// all veto events are waitable
return rc;
return rc;
}
void VBoxVetoEvent::uninit()
{
if (!m)
return;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
if (aVeto)
return S_OK;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
return S_OK;
}
{
if (ComSafeArrayOutIsNull(aVetos))
return E_POINTER;
AutoCaller autoCaller(this);
return autoCaller.rc();
int i = 0;
++it, ++i)
{
}
return S_OK;
}
static const int LastEvent = (int)VBoxEventType_Last;
/**
* Class replacing std::list and able to provide required stability
* during iteration. It's acheived by delaying structural modifications
* to the list till the moment particular element is no longer used by
* current iterators.
*/
class EventMapRecord
{
public:
/**
* We have to be double linked, as structural modifications in list are delayed
* till element removed, so we have to know our previous one to update its next
*/
bool mAlive;
private:
public:
{}
{
}
{
if (mNext)
if (mPrev)
}
void addRef()
{
}
void release()
{
if (ASMAtomicDecS32(&mRefCnt) <= 0)
delete this;
}
// Called when an element is no longer needed
void kill()
{
mAlive = false;
release();
}
{
}
friend class EventMapList;
};
class EventMapList
{
public:
:
mHead(0),
mSize(0)
{}
~EventMapList()
{
while (pCur)
{
}
}
/*
* Elements have to be added to the front of the list, to make sure
* that iterators doesn't see newly added listeners, and iteration
* will always complete.
*/
{
if (mHead)
mSize++;
}
/*
* Mark element as removed, actual removal could be delayed until
* all consumers release it too. This helps to keep list stable
* enough for iterators to allow long and probably intrusive callbacks.
*/
{
while (pCur)
{
{
mSize--;
// break?
}
}
}
{
return mSize;
}
struct iterator
{
iterator() :
mCur(0)
{}
explicit
{
// Prevent element removal, till we're at it
if (mCur)
}
~iterator()
{
if (mCur)
}
operator*() const
{
}
operator++()
{
do {
// now we can safely release previous element
// And grab the new current
if (mCur)
return *this;
}
bool
{
}
bool
{
}
};
{
}
{
return iterator(0);
}
};
class ListenerRecord
{
private:
public:
~ListenerRecord();
HRESULT process(IEvent *aEvent, BOOL aWaitable, PendingEventsMap::iterator &pit, AutoLockBase &alock);
void addRef()
{
}
void release()
{
if (ASMAtomicDecS32(&mRefCnt) <= 0)
delete this;
}
{
return mActive;
}
friend class EventSource;
};
/* Handy class with semantics close to ComPtr, but for list records */
template<typename Held>
class RecordHolder
{
public:
{
addref();
}
{
addref();
}
:
held(0)
{
}
~RecordHolder()
{
release();
}
{
return held;
}
{
return *this;
}
private:
void addref()
{
if (held)
}
void release()
{
if (held)
}
{
if (that_p)
release();
}
};
struct EventSource::Data
{
Data()
{}
};
/**
* This function defines what wildcard expands to.
*/
{
switch (who)
{
case VBoxEventType_Any:
return TRUE;
case VBoxEventType_Vetoable:
return (what == VBoxEventType_OnExtraDataCanChange)
|| (what == VBoxEventType_OnCanShowWindow);
return (what == VBoxEventType_OnMachineStateChanged)
|| (what == VBoxEventType_OnGuestPropertyChanged);
return (what == VBoxEventType_OnSnapshotTaken)
|| (what == VBoxEventType_OnSnapshotDeleted)
|| (what == VBoxEventType_OnSnapshotChanged) ;
case VBoxEventType_InputEvent:
return (what == VBoxEventType_OnKeyboardLedsChanged)
case VBoxEventType_Invalid:
return FALSE;
default:
break;
}
}
EventSource *aOwner) :
{
{
for (int j = FirstEvent; j < LastEvent; j++)
{
{
}
}
}
if (!mActive)
{
::RTCritSectInit(&mcsQLock);
::RTSemEventCreate(&mQEvent);
mLastRead = RTTimeMilliTS();
}
else
{
mLastRead = 0;
}
}
{
/* Remove references to us from the event map */
for (int j = FirstEvent; j < LastEvent; j++)
{
}
if (!mActive)
{
// at this moment nobody could add elements to our queue, so we can safely
// clean it up, otherwise there will be pending events map elements
while (true)
{
break;
if (aWaitable)
{
}
}
::RTCritSectDelete(&mcsQLock);
}
}
{
if (mActive)
{
/*
* We release lock here to allow modifying ops on EventSource inside callback.
*/
if (mListener)
{
#ifdef RT_OS_WINDOWS
#endif
}
if (aWaitable)
return rc;
}
}
{
// put an event the queue
::RTCritSectEnter(&mcsQLock);
// If there was no events reading from the listener for the long time,
// and events keep coming, or queue is oversized we shall unregister this listener.
{
::RTCritSectLeave(&mcsQLock);
return E_ABORT;
}
/* if same event is being pushed multiple times - it's reusable event and
we don't really need multiple instances of it in the queue */
(void)aEvent;
else
::RTCritSectLeave(&mcsQLock);
// notify waiters
return S_OK;
}
{
if (mActive)
return VBOX_E_INVALID_OBJECT_STATE;
// retain listener record
::RTCritSectEnter(&mcsQLock);
mLastRead = RTTimeMilliTS();
{
::RTCritSectLeave(&mcsQLock);
// Speed up common case
if (aTimeout == 0)
{
return S_OK;
}
// release lock while waiting, listener will not go away due to above holder
// reacquire lock
::RTCritSectEnter(&mcsQLock);
}
{
}
else
{
}
::RTCritSectLeave(&mcsQLock);
return S_OK;
}
{
{
aEvent->SetProcessed();
}
return S_OK;
}
{}
{}
{
m = new Data;
return BaseFinalConstruct();
}
void EventSource::FinalRelease()
{
uninit();
delete m;
}
{
AutoInitSpan autoInitSpan(this);
/* Confirm a successful initialization */
return rc;
}
void EventSource::uninit()
{
AutoUninitSpan autoUninitSpan(this);
if (autoUninitSpan.uninitDone())
return;
m->mListeners.clear();
// m->mEvMap shall be cleared at this point too by destructors, assert?
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
{
return setError(E_INVALIDARG,
tr("This listener already registered"));
}
return S_OK;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
{
{
// destructor removes refs from the event map
}
else
{
tr("Listener was never registered"));
}
}
{
}
return rc;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
do {
/* Anyone interested in this event? */
if (cListeners == 0)
{
aEvent->SetProcessed();
break; // just leave the lock and update event object state
}
if (aWaitable)
{
// we keep iterator here to allow processing active listeners without
// pending events lookup
}
++it)
{
// keep listener record reference, in case someone will remove it while in callback
/*
* We pass lock here to allow modifying ops on EventSource inside callback
* in active mode. Note that we expect list iterator stability as 'alock'
* could be temporary released when calling event handler.
*/
/* Note that E_ABORT is used above to signal that a passive
* listener was unregistered due to not picking up its event.
* This overlaps with XPCOM specific use of E_ABORT to signal
* death of an active listener, but that's irrelevant here. */
{
}
// anything else to do with cbRc?
}
} while (0);
/* We leave the lock here */
if (aWaitable)
else
*aProcessed = TRUE;
return hrc;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
else
tr("Listener was never registered"));
if (rc == VBOX_E_INVALID_OBJECT_STATE)
return rc;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
{
return setError(E_INVALIDARG,
tr("Only applicable to passive listeners"));
if (aWaitable)
{
{
AssertFailed();
tr("Unknown event"));
}
else
}
else
{
// for non-waitable events we're done
}
}
else
{
tr("Listener was never registered"));
}
return rc;
}
/**
* This class serves as feasible listener implementation
* which could be used by clients not able to create local
* COM objects, but still willing to receive event
* notifications in passive mode, such as webservices.
*/
class ATL_NO_VTABLE PassiveEventListener :
public VirtualBoxBase,
{
public:
{}
{}
{
return BaseFinalConstruct();
}
void FinalRelease()
{
}
// IEventListener methods
{
ComAssertMsgRet(false, ("HandleEvent() of wrapper shall never be called"),
E_FAIL);
}
};
/* Proxy listener class, used to aggregate multiple event sources into one */
class ATL_NO_VTABLE ProxyEventListener :
public VirtualBoxBase,
{
public:
{}
{}
{
return BaseFinalConstruct();
}
void FinalRelease()
{
}
{
return S_OK;
}
// IEventListener methods
{
if (mSource)
else
return S_OK;
}
};
class ATL_NO_VTABLE EventSourceAggregator :
public VirtualBoxBase,
{
/* key is weak reference */
public:
{}
{}
{
return BaseFinalConstruct();
}
void FinalRelease()
{
}
// internal public
// IEventSource methods
BOOL *aProcessed);
protected:
IEventListener **aProxy);
IEventListener **aProxy);
};
#ifdef VBOX_WITH_XPCOM
#endif
{
AutoCaller autoCaller(this);
return autoCaller.rc();
E_FAIL);
return S_OK;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
E_FAIL);
return rc;
return S_OK;
}
{
AutoInitSpan autoInitSpan(this);
E_FAIL);
E_FAIL);
{
}
/* Confirm a successful initialization */
return rc;
}
{
}
{
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
return rc;
++it)
{
/* Register active proxy listener on real event source */
}
/* And add real listener on our event source */
return rc;
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
return rc;
++it)
{
}
return removeProxyListener(aListener);
}
{
AutoCaller autoCaller(this);
return autoCaller.rc();
/* Aggregator event source shall not have direct event firing, but we may
wish to support aggregation chains */
++it)
{
/* Current behavior is that aggregator's FireEvent() always succeeds,
so that multiple event sources don't affect each other. */
}
return S_OK;
}
{
}
{
}
{
E_FAIL);
return rc;
return setError(E_INVALIDARG,
tr("This listener already registered"));
return S_OK;
}
{
return setError(E_INVALIDARG,
tr("This listener never registered"));
return S_OK;
}
{
return setError(E_INVALIDARG,
tr("This listener never registered"));
return S_OK;
}