ElementQueue

Here's a useful construct for Groove tool developers, especially when working with third-party ActiveX controls for UI. The ElementQueue is really easy to use, but I'll preface this with some chat about MVC and threading to give an example of where I needed it. I'm sure you'll have other applications.

In the MVC (model-view-controller) structure, your tool will receive events from the model when its dataset changes - locally (because you did something at the UI, usually) or remotely (because another member in the space triggered a data change, which was disseminated to your device). Typically, you'll install some listeners in your controller (UI gluecode) to process these events when they happen, and change the current state of the UI to reflect the new information.

When your UI is built with an ActiveX control, you can hit threading issues. This is especially important where your ActiveX control is a facade onto a single-process application (ie. the control silently loads a full application in background): I've seen this with Acrobat and MapPoint. The pipe between "controller" and "view" might need to play nice.

Groove runs a single thread for UI, and several background threads for everything else. So when Dynamics processes commands for an Engine (your Model), that's always on one of the background worker threads. The engine then fires a COM event, to which your controller code (in the UI thread) is listening. Groove proxies the event onto the UI thread for your gluecode to pick up. Then you handle the event, by talking to your user interface. Like this (JavaScript):

function PropertyList_OnPropertyChanged( sName, pValue, bRemote )

{

	switch( sPropertyName )

	{

		case "something":

			MyUIControl.DoStuff( sName, pValue );

	}

}

Let's say that your UI is an ActiveX control, and it's busy right now. It won't be able to process your call to its .DoStuff() method (or whatever), and the default behaviour in these circumstances seems to be: die disgracefully. So we really want to queue the event until a later time when we know the UI has settled down.

For this, I use an "idle handler" (although you could easily use a timer instead). By registering as an idle handler, you have a function be called whenever the Groove UI thread has some spare time - this seems to be roughly every 20 milliseconds. The idle handler is a great place to perform occasional UI update, by reading from a queue of work-to-do. So let's set up an idle handler:

<SCRIPT>

var g_IdleManagerCookie = 0;


function Initialize()

{

	// Register as an idle handler.

	var pIdleManager = GrooveScriptFunctions.CreateNewObject( "Groove.IdleManager" );

	var pIdleHandler = ScriptHostComponent.GetScriptDispatch( "[IGrooveIdleHandler]" );

	g_IdleManagerCookie = pIdleManager.AddHandler( pIdleHandler );

}

function Terminate()

{

	if( g_IdleManagerCookie )

	{

		var pIdleManager = GrooveScriptFunctions.CreateNewObject( "Groove.IdleManager" );

		pIdleManager.RemoveHandler( g_IdleManagerCookie );

		g_IdleManagerCookie = 0;

	}

}

</SCRIPT>

<SCRIPTINTERFACE IIDName="IGrooveIdleHandler"

IID="{2ACCD3C1-9C5A-11d3-80CC-00500487878E}"

LIBID="{4253A641-5FA3-11d2-98C2-0080C7E30BA4}">

function OnIdle( nIdleCount )

{

	HandleQueuedCommands();

}

</SCRIPTINTERFACE>

Now to set up an event queue, and a HandleQueuedCommands() function to dequeue work items.

Groove's ElementQueue API is just that: a FIFO queue of XML elements (children of a parent XML element; in this case, a temporary element created just to hold the queue). You can enqueue arbitrary pieces of XML, and dequeue them later. Since the payload is just XML, it's easy to wrap an event and its parameters into an element for the queue. You might want to queue many different types of command; just use elements with different names. It's not necessary to declare a formal schema for these elements, but naming them sensibly helps keep your code readable.

So, in Initialize(),

// Make a temporary element queue for handling changed records
g_pSM = GrooveScriptFunctions.CreateNewObject("Groove.StorageManager");
var pElQueue = g_pSM.CreateTemporaryElement( "urn:mynamespace.com:MyCommandQueue" );
pElQueue.SetDeleteOnRelease( true );
g_pLocalQueue = pElQueue.OpenElementQueue();

When you want to enqueue something - for example, an event called from your datamodel - just wrap it into an element and place it in the queue:

function SomeObject_OnUpdate( EventParam1, EventParam2 )
{
var pEl = g_pSM.CreateTemporaryElement( "urn:mynamespace.com:MyQueueElement" );
pEl.SetAttributeAsDouble( "Param1", EventParam1 );
pEl.SetAttributeAsDouble( "Param2", EventParam2 );
g_pLocalQueue.Enqueue( pEl );
}

Then, when the UI is idle, look at the queue and handle any commands which we see there. You'll get the best performance if you process the whole queue in the idle handler (rather than just handling one queued command at a time).

function HandleQueuedCommands()
{
if( !IsTheUIReady() ) return; // we'll just do it later!
var pEnum = g_pLocalQueue.DequeueEnum();
while( pEnum.HasMore() )
HandleQueuedCommand( pEnum.OpenNext() );
}

function HandleQueuedCommand( pElement )
{
if( pElement.OpenName()=="urn:mynamespace.com:MyQueueElement" )
{
var sParam1 = pEl.OpenAttribute( "Param1" );
var sParam2 = pEl.OpenAttribute( "Param2" );
MyActiveXControl.DoStuff( sParam1, sParam2 );
}
}

To recap:

• Create a temporary element to hold a queue of "command" elements which we'll process when we have time
  
• Register an IdleHandler to process the queue when the UI is idle (or just use a timer, if you like)
  
• When events happen to your controller, wrap them up as an XML element and enqueue them
  
• OnIdle, dequeue and handle any waiting commands.
  

Of course there are several other ways to use an element queue. The queue could be persisted, or even disseminated (on an element in a PropertyList, for example) - that could be a nice foundation for a distributed-processing application.