I’m historically (and well, currently) a .NET developer, but find the idea of a GAE based game server platform intriguing. But hey, I’m pretty much a 1 trick pony: “C# or nuthin.” (I can write C++ but hate it), so how do I get into the world of “weird” java buzzwords like servlets and WAR, in addition to the platform specific knowledge that makes up GAE?

One way would be to force one of Novaleaf’s webdevs to sit down and teach me. I might just do that, but… after I give it a try myself.   Here’s the steps I took to learn GAE’s basics, and get a “hello world” app running. I hope it’s useful for other .NET developers looking to expand their skills in a relatively painless way.

First: Get a high-level picture.

I skimmed Google’s online resources about GAE and it’s various features. and learned from a high-level what GAE can and can not do, and what it will be able to do in the near future.  I prefer to do this high-level overview first to frame the capabilities of the platform, so later when doing in-depth tutorials I can frame the knowledge in context to how it’d fit into my project’s needs.

I was a bit surprised about how well described it is, at least relative to Sun’s Java/Javadoc references. I am sure that for Java developers, the documentation is perfectly fine… but for people starting out, it’s a bit painful to figure out the difference between J2SE, J2EE, that Java “2″ is actually v1.2, etc etc…  Anyway, no need to go into that here, right ;)

Second:  will GAE do what I need?

Once I understand the general capabilities of GAE, I ask myself if it will do what I need?   Well, I have a ton of ideas floating in my head, but to put this in perspective for a “simple game server” here’s some key points:

1. GAE scales very well with multiple users (each request is on a separate thread)
2. Storing intra-gamestate will be too expensive (GAE stores all state in database, so high-frequency read/writes will be monetarily expensive)
3. Storing macro-level metagame information (low-frequency user information and matchmaking data) seems to be a good match for GAE’s feature set
4. Per-user server polling is the only viable option for GAE right now  (a socket api is in development but not yet ready)
5. Threading is not supported right now (in development) so no multithreaded fancyness is available.
6. Supports XMPP based chat protocol
7. To summarize, GAE seems suitable for synchronizing with users every few minutes, so for savegame, matchmaking, topscores, achievements, etc.    but not for high-frequency use .

Third: Find a good book.

I searched amazon for the highest rated books on the matter, and settled with “Programming Google App Engine“.

I am currently on chapter 2 of this book, following the tutorials to put together a “hello world”.  Seems good, however their explanations detail using Eclipse,  which is nice and all (and free) but not realy that user friendly to .NET developers comfortable with Visual Studio.

Fourth: Setting up the right tools

I did some research as to the most visual-studio-like java IDE, and came up with IntelliJ.  Their Ultimate Edition also comes with GAE and Google Web Toolkit integration, so seems great to me.     I’ll quickly summarize the steps I take to get the tools setup:

1. Install Java6 JDK from Sun’s website (J2SE x64 is what I used) http://www.oracle.com/technetwork/java/javase/downloads/index.html  Note that you must use v6.x with GAE
2. Install IntelliJ Ultimate (11.x is what i used)
3. Download and extract the GAE SDK to some reference folder on your HD:   http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Java

Run IntelliJ and create a new project with the following options:

1. Setup a new project (Java Module)
2. Under technologies, choose “Google App Engine”, choose the right SDK dir that you extracted the GAE SDK to.
3. If not set, point JDK dir to the program files\java\jdk1.6.x dir  (File–>Project Structure–>Project)
4. Add J2EE servlet references:  File–>ProjectStructure–>Libraries–>AppEngine API–>Classes->Attach Directory:   “%PATH_TO_APP_ENGINE_API%\lib\shared”  also add \lib\orm\ and \lib\user\ and \lib\
5. Add GAE Javadocs for inline documentation:   File–>ProjectStructure–>Libraries–>AppEngine API–>Specify Documentation URL–>“http://code.google.com/appengine/docs/java/javadoc/” also add “http://docs.oracle.com/cd/E17410_01/javaee/6/api/” for the shared library stuff, as GAE ships with parts of J2EE, but without the docs of it, so you have to point to Sun’s docs instead.
6. Reconfigure Intellij for non-case-sensitive autocomplete: File–>Settings–>Editor–>Code Completion–>Case Sensitive completion–>None
7. seems that the basic dir layout isn’t compatible with GAE.  move the META-INF dir to be under the src dir
8. For JPA persistence to work (needed for the book’s tutorials) you must change some settings:   File–>Project Structure–>Modules–>Web–>GAE.  Check “Run Enhancer” and set the persistence options to JPA.

After that, you should be able to follow the tutorials as shown in the Book I mentioned earlier, or get started with google’s own tutorials.

Summary:  Pretty easy!

In total, I spent about 3 days figuring out these details and finish up my first “hello world” app and getting it published on GAE.   If this information proves useful (or not), please leave a comment.  I’d love to hear.

Primary Aim: (education)
to provide practical knowledge to those recently entered into the “system parallelization” field. I will describe the multithread relevent design process that went into the design and development of Novaleaf‘s new WorkerThread subsystem.

First step, what’s the goal? (use case scenario)
it’s very important for any development (not just multithreading) to fully understand your “functional objectives” before starting to architect, and then to architect your system (high-level design) before you code.

Here is my scenario:
Synchronization between a “main engine thread” and a reusable “worker thread” subsystem. main and worker threads should execute loops at a 1:1 frequency, with the start/end of the worker thread’s loop tied to a specific part of the engine’s loop code.

illustration of the scenario:

High level design:

1. “engine wait for worker”: need main thread sync-point to wait for worker to finish
2. “worker wait for engine”: need worker to wait until main thread resumes worker (starts next loop)
3. “others wait for worker” also need other systems to be able to wait for worker to finish. an example is if there is a shared resource that multiple threads access.
4. Worker owns it’s own thread:  The worker runs in an infinite loop, pausing when waiting for the engine (Design point #2).
5. Keep it stupid simple!  There are many ways I could sexify (complicate) this setup, but there are three reasons why i do not:
   1. Educational purposes
   2. Complex thread synchronization has bugs (race conditions)
   3. “I use this in real life” (it works)

Implementation Phase 1: (identify existing solutions)

Design point #2,
“worker wait for engine” shows that to fulfill this functionality, only 1 thread (worker) needs to wait for the main engine thread. In this case, the .NET BCL class AutoResetEvent works nicely because it will allow a single waiter (the worker) through when the main thread says it’s ready (signals).


//**worker loop, (full workflow)**
while(true){
//wait for engine to allow this worker to start it's next loop
waitForEngine_AutoResetEvent.WaitOne();

//do fancy asynchronous work here!

//worker informs engine that it is finished
waitForWorker_ManualResetEvent.Set();
}

Above is the worker thread’s loop. it waits for the engine to signal it to proceed, does work, then informs the engine that it’s finished.

Now for what the engine’s code (partially) looks like:

//**engine thread**
//allow 1 waiting thread through,
//or if none are waiting, exactly 1 future caller through
//then automatically (instantly) resets to blocking.
waitForEngine_AutoResetEvent.Set();

We can not use ManualResetEvent because we need to call .Set() and .Reset() independently:

//**engine thread with race condition (bad)**
//allow waiting code through
waitForEngine_ManualResetEvent.Set();
//set to blocking
waitForEngine_ManualResetEvent.Reset();

This doesn’t work because of the situation when worker has called waitForWorker_ManualResetEvent.Set(); but has not yet looped back and made the .WaitOne() call. the worker’s execution may be suspended between those two lines, and thus the engine may itself .Set() and .Reset() before the worker even gets to the next line. It sounds unlikely, and it is, but it is not safe (it may fail 1 out of 1 million times).

Design point #1,
“engine wait for worker”: we could get by with the design point #2 solution “AutoResetEvent” stated above, however we need to consider Design point #3.

Design point #3,
“others wait for worker”: because of this, the AutoResetEvent solution doesn’t work.

//fails because only the first waiter will be allowed through
//multiple systems may wait on the worker thread completing.
waitForWorker_AutoResetEvent.WaitOne();

however we also can not use the ManualResetEvent, because of the problem already outlined above in Design point#2.
If you look at the other classes in the .NET BCL System.Threading namespace, none of those seem to be a good fit for this problem. So looks like we need to write our own synchronization primitive!

Implementation Phase 2: (rethinking the problem)

To recap, we need a synchronization primitive similar to AutoResetEvent, however needs to only reset (block future calles) after the main engine thread finishes waiting. All threads, including the engine, should unblock once the worker thread’s loop completes.

After thinking through the problem, it turns out we actually DO NOT need anything more complex than ManualResetEvent for the engine-wait-on-worker. here’s why:

1. if our worker calls waitForWorker_ManualResetEvent.Set() then all waiting threads will clear, and all future waits will clear
2. if the engine calls waitForWorker_ManualResetEvent.Reset() after waiting for the worker to finish but before launching the worker’s next loop, then the engine’s target workflow is preserved.
3. Here’s the kicker: if other threads wait on the worker, they will suffer race conditions (example: worker’s next loop starts before the other thread’s call to .WaitOne() even finishes). Thus this workflow is unsupported. Other threads must synchronize with main, not with workers.

Implementation Phase 3: (Final take away)
Please pay special attention to my “Here’s the kicker” list-item above. This shows that while my initial thoughts were to allow any “other thread” to synchronize with the worker thread, this requirement would have resulted in the construction of a custom (and complex) synchronization primitive. Also, on closer inspection this seems to be a significantly troubling anti-pattern which should consciously be avoided.


//**main thread, (full workflow)**
void Engine_UpdateTheWorker(float time)
{
//wait for worker's previous loop to finish
waitForWorker_manualResetEvent.WaitOne();
//reset our worker's waitEvent back to blocking
waitForWorker_manualResetEvent.Reset();

//do data synchronization
workerLoopTime=time;

//signal our worker to start it's next loop
waitForEngine_autoResetEvent.Set();
}

Above is the full implementation of the engine’s synchronization code. This and the worker’s loop code further above is copy-paste-programmer friendly for those looking to quickly utilize the architecture I have provided.

Conclusion: really really try not to re-invent the wheel.
There certainly will be times where the base synchronization primitives will not be enough to get the job done, but with the .NET 4.0 BCL System.Threading additions, those will (should) be few and far between. I hope that this step-by-step on the process I went through for re-designing Novaleaf’s WorkerThread subsystem helps illustrate this point.

Since we’ve been parallelizing our engine, one problem I keep seeing pop up is how to manage inter-thread communications: everyone does it differently, and in doing so, has to rewrite the basic data workflow and synchronization (and do so in their own unique way)  Due to the subtle nature of race-conditions, this is especially dangerous.

So, I set about designing a solution.  My original solution was called “PushProcess” but after doing some searches on wikipedia for naming conventions, I have renamed it to “MapFold” (not to be confused with Google’s MapReduce).

Workflow Diagram

Data Transformation

MapFold is an abstract class, thus derived classes are required to add their own custom Map and Fold computational algorithm, giving clear mechanisms for data transformation.

• Map() allows data being input from the User threads to be transformed immediately (on the same thread).
• Fold() allows enqueued data to be transformed by the Owner thread before or during consumption.

The primary benefit of all of this is encapsulation of all this data transformation logic in a single location (the derived class) and providing an obvious extensibility point for performing these transformations.

Another major benefit of MapFold is the encapsulation and reuse of enqueue/dequeue/synchronization logic.

Source Code (C#)

/// <summary>
/// Design Pattern for Multithread data synchronization/communication
/// <para>this base class provides the workflow for enqueueing data (<see cref="TInput"/>) from multiple threads, 
/// and preparing (transforming to <see cref="TIntermediate"/> via the Map method) it for use by this class's owner 
/// (usually a system on a <see cref="WorkerThread"/> but not required). </para>
/// <para>the data can be transformed at 2 positions: 
/// <para><see cref="TInput"/> --> <see cref="TIntermediate"/>:  first by the <see cref="Map"/> method 
/// (which occurs immediatly upon invocation on the same thread as the caller)</para>
/// <para><see cref="TIntermediate"/> --> output (custom): second, 
/// when the <see cref="Fold"/>() method is invoked (by the owner), 
/// additional data transformations may occur. 
/// the output data from this <see cref="Fold"/>() method depends on the descendant 
/// class overriding this abstract method. </para>
/// <para> See the <see cref="FrameState"/> class for an example usage (enqueing framestate changes every frame to worker threads)</para>
/// </summary>
/// <typeparam name="TInput"></typeparam>
/// <typeparam name="TIntermediate">intermediate data type written by <see cref="Map"/>() and processed by <see cref="Fold"/>()</typeparam>
/// <remarks></remarks>
public abstract class MapFold_Example<TInput, TIntermediate>
{
	/// <summary>
	/// for internal thread safety use only.
	/// </summary>
	private object _lock = new object();
 
	/// <summary>
	/// calls to the <see cref="Map"/>() method enqueue to this.  (locked so threadsafe)
	/// </summary>
	private Queue<TIntermediate> mapQueue = new Queue<TIntermediate>();
	/// <summary>
	/// calls to <see cref="Fold"/>() consume this.  (we swap-buffer with <see cref="mapQueue"/> every call so this is threadsafe consumption)
	/// </summary>
	private Queue<TIntermediate> foldQueue = new Queue<TIntermediate>();
 
	/// <summary>
	/// thread-safe enqueue <see cref="TInput"/> for consumption by this object owner.
	/// </summary>
	/// <param name="input"></param>
	/// <remarks>
	/// <para>input will be transformed to <see cref="TIntermediate"/> during this method call.</para>
	/// <para>http://en.wikipedia.org/wiki/Map_(higher-order_function)</para>
	/// </remarks>
	public void Map(TInput input)
	{
		TIntermediate intermediate;
		Map(input, out intermediate);
		lock (_lock)
		{
			//only the actual enqueue is inside the lock to minimize waits by multiple threads
			mapQueue.Enqueue(intermediate);
		}
	}
 
	/// <summary>
	/// override this method to transform <see cref="input"/> --> <see cref="intermediate"/>
	/// </summary>
	/// <param name="input"></param>
	/// <param name="intermediate"></param>
	/// <remarks>this work occurs on the user's thread (the "external" execution calling <see cref="Map"/>)</remarks>
	protected abstract void Map(TInput input, out TIntermediate intermediate);
 
	public void Fold()
	{
		Fold(default(Action<Queue<TIntermediate>>));
	}
 
	/// <summary>
	/// start computations on all currently enqueued <see cref="TIntermediate"/>
	/// <para>this should be invoked by this object's 'owner', probably once per frame.</para>
	/// </summary>
	/// <param name="foldDelegate">if you pass a delegate, this will be executed first, before the internal Fold implementation (if any)</param>
	/// <remarks>http://en.wikipedia.org/wiki/Fold_(higher-order_function)</remarks>
	public void Fold(Action<Queue<TIntermediate>> foldDelegate)
	{
 
		lock (_lock)
		{
			var temp = foldQueue;
			foldQueue = mapQueue;
			mapQueue = temp;
		}
		if (foldDelegate != null)
		{
			foldDelegate(foldQueue);
		}
		Fold(foldQueue);
		foldQueue.Clear();
	}
	/// <summary>
	/// override this method to specify implementation for the <see cref="Fold"/>() method.
	/// <para> start computations on all currently enqueued <see cref="TIntermediate"/></para>
	/// <para>this should be invoked by this object's 'owner', probably once per frame.</para>
	/// </summary>
	/// <param name="intermediateQueue">all currently enqueued values sent via the <see cref="Map"/>() method (after being transformed <see cref="TInput"/> --> <see cref="TIntermediate"/>
	/// <para>usage note: this queue will automatically be cleared after this method completes</para></param>
	protected abstract void Fold(Queue<TIntermediate> intermediateQueue);
 
}
 
/// <summary>
/// an "easy to use" concrete class that allows the min-workflow of MapFold 
/// without the need to create your own custom class
/// </summary>
/// <typeparam name="TValue"></typeparam>
public class MapFold_Example<TValue> : MapFold_Example<TValue, TValue>
{
	protected override void Fold(Queue<TValue> intermediateQueue)
	{
		//no op (owner class can interact with the intermediateQueue through the value returned by the base class's .Fold() method.
	}
	protected override void Map(TValue input, out TValue intermediate)
	{
		//no work: intermediate is of same type/value as enqueued via the original call to the base class's .Map() method
		intermediate = input;
	}
}

An Example

Instead of explaining why this is better than continuously “rolling your own”, I’ll give an example system using this MapFold workflow:

/// <summary>
/// This example shows a straight forward and simple way to synchronize 
/// multithread communication to a render system.
/// <para>For the sake of simplicity, some optimizations were omitted 
/// (such as reduction of value-type copies, etc).</para>
/// </summary>
public class RenderManager_Example
{
	/// <summary>
	/// intermediate data type
	/// </summary>
	private struct RenderTransaction
	{
		public enum TransactionStatus
		{
			Alloc,
			Free,
			Modify,
		}
 
		/// <summary>
		/// transaction being done
		/// </summary>
		public TransactionStatus transaction;
		/// <summary>
		/// object reference for internal render tracking and external coordination.
		/// </summary>
		public int objectId;
		/// <summary>
		/// world transform
		/// <para>set when transaction==Alloc|Modify</para>
		/// </summary>
		public object xform;
		/// <summary>
		/// asset used by this object.
		/// <para>set when transaction==Alloc</para>
		/// </summary>
		public int assetId;
	}
 
	/// <summary>
	/// an instance of our mapFold for this renderManager
	/// </summary>
	private MapFold_Example<RenderTransaction> mapFold;
 
	public RenderManager_Example()
	{
		mapFold = new MapFold_Example<RenderTransaction>();
	}
 
	#region public (thread safe) methods
	/// <summary>
	/// allocate space in our render system for a new object
	/// </summary>
	/// <param name="assetId">asset this object uses</param>
	/// <param name="objectId">id for our object</param>
	/// <param name="xform">starting world transform</param>
	public void Alloc(int assetId, int objectId, object xform)
	{
		//invoke our base class's mapFold.Map() which does a thread-safe FIFO enqueue
		mapFold.Map(new RenderTransaction()
			{
				assetId = assetId,
				objectId = objectId,
				xform = xform,
				transaction = RenderTransaction.TransactionStatus.Alloc
			}
								);
	}
 
	/// <summary>
	/// remove the object from rendering
	/// </summary>
	/// <param name="objectId"></param>
	public void Free(int objectId)
	{
		//invoke our base class's mapFold.Map() which does a thread-safe FIFO enqueue
		mapFold.Map(new RenderTransaction()
			{
				objectId = objectId,
				transaction = RenderTransaction.TransactionStatus.Free
			}
			);
	}
	/// <summary>
	/// change this object's runtime render properties
	/// </summary>
	/// <param name="objectId"></param>
	/// <param name="xform"></param>
	public void Modify(int objectId, object newXform)
	{
		//invoke our base class's mapFold.Map() which does a thread-safe FIFO enqueue
		mapFold.Map(new RenderTransaction()
		{
			objectId = objectId,
			xform = newXform,
			transaction = RenderTransaction.TransactionStatus.Modify
		}
		);
	}
 
	#endregion
 
	#region private worker methods (execute during the RenderManger's .Update(), which is assumed to execute on it's own thread)
 
	private void Owner_ProcessTransactions(Queue<RenderTransaction> toProcess)
	{
		//does a FIFO enumeration of enqueued data (from .Map()
		foreach (var renderTransaction in toProcess)
		{
			switch (renderTransaction.transaction)
			{
				case RenderTransaction.TransactionStatus.Alloc:
					Owner_Alloc(renderTransaction.assetId, renderTransaction.objectId, renderTransaction.xform);
					break;
				case RenderTransaction.TransactionStatus.Free:
					Owner_Free(renderTransaction.objectId);
					break;
				case RenderTransaction.TransactionStatus.Modify:
					Owner_Modify(renderTransaction.objectId, renderTransaction.xform);
					break;
				default:
					throw new NotSupportedException();
			}
		}
	}
 
	private void Owner_Alloc(int assetId, int objectId, object xform)
	{
		//allocate a slot in our render system
	}
	private void Owner_Free(int objectId)
	{
		//delete the object from our render system
	}
	private void Owner_Modify(int objectId, object xform)
	{
		//modify position of existing object in our render system
	}
	#endregion
 
	/// <summary>
	/// this .Update() method is meant to be executed in our render thread
	/// </summary>
	public void Update()
	{
		//FIFO execution of enqueued .Map() data (Alloc,Modify,Free)
		mapFold.Fold(Owner_ProcessTransactions);
 
		//draw goes here
	}
 
}

So is this unique?

I am under the impression that while this workflow is certainly not unique, few encapsulate this pattern into a discrete object.  What about you?  Do you do something similar?  Lets discuss in the comments!

So to help out all the “async noobs”, here is my C#  implementation of an excellent lock-free queue paper.

If you don’t know what a “lock-free” algorithm is, this code is really not for your consumption, as it is going to be a bit too advanced.  If you are an ‘asynchronous beginner’ or even an expert, the best book on the subject I’ve seen is “The Art of Multiprocessor Programming” so give that a read.

And yes, this is in C#.  If you are a C/C++ developer, weep your bitter tears  :)

	///
	/// A lock-free queue.
	///
Usage Note: thread safe, fast performance
	///
	/// by jason swearingen, copyright novaleaf software.  all rights reserved.
	///
Released under the MSPL: http://www.opensource.org/licenses/ms-pl
	///
idea / core algorithm taken from http://www.research.ibm.com/people/m/michael/podc-1996.pdf
	/// inline comments are direct transcriptions of this paper's psudocode (thus this queue is virtually a 1:1 implementation of this awesome paper)
	///
	///
	[ThreadSafe]
	[DebuggerStepThrough]
	public class SafeQueue
	{
		//structure pointer t fptr: pointer to node t, count: unsigned integerg
		//structure node t fvalue: data type, next: pointer tg
		private class Node
		{
			public Node next;
			public T value;
		}
 
#if DEBUG
		public int Count
		{
			get
			{
 
				return _count;
 
			}
		}
 
#endif
 
		//structure queue t fHead: pointer t, Tail: pointer tg
		private Node _head, _tail;
 
		public SafeQueue()
		{
			//initialize(Q: pointer to queue t)
			//node = new node() # Allocate a free node
			//node–>next.ptr = NULL # Make it the only node in the linked list
			//Q–>Head = Q–>Tail = node # Both Head and Tail point to it
			_head = _tail = new Node();
		}
 
		private volatile int _count = 0;
 
		public bool IsEmpty
		{
			get { return _count == 0; }
		}
 
		//enqueue(Q: pointer to queue t, value: data type)
 
		public virtual void Enqueue(T value)
		{
			Enqueue(ref value);
		}
 
		public virtual void Enqueue(ref T value)
		{
 
			//E1: node = new node() # Allocate a new node from the free list
			//E2: node–>value = value # Copy enqueued value into node
			//E3: node–>next.ptr = NULL # SafeSet next pointer of node to NULL
			Node toAdd = new Node();
			toAdd.value = value;
			Node tail = null;
			Node temp;
 
			//E4: loop # Keep trying until Enqueue is done
			while (true)
			{
				//E5: tail = Q–>Tail # Read Tail.ptr and Tail.count together
				//E6: next = tail.ptr–>next # Read next ptr and count fields together
				tail = this._tail;
				Node next = tail.next;
 
				//E7: if tail == Q–>Tail # Are tail and next consistent?
				if (Node.ReferenceEquals(tail, this._tail))
				{
					//E8: if next.ptr == NULL # Was Tail pointing to the last node?
					if (next == null)
					{
						//E9: if CAS(&tail.ptr–>next, next, ) # Try to link node at the end of the linked list
						temp = Interlocked.CompareExchange(ref tail.next, toAdd, next);
						if (Node.ReferenceEquals(temp, next))
						{
							//E10: break # Enqueue is done. Exit loop
							break;
							//E11: endif
						}
 
					}//E12: else # Tail was not pointing to the last node
					else
					{
						//E13: CAS(&Q–>Tail, tail, ) # Try to swing Tail to the next node for try again
						Interlocked.CompareExchange(ref this._tail, next, tail);
						//E14: endif
					}
					//E15: endif
				}
				//E16: endloop
			}
			//E17: CAS(&Q–>Tail, tail, ) # Enqueue is done. Try to swing Tail to the inserted node
			Interlocked.CompareExchange(ref this._tail, toAdd, tail);
			Interlocked.Increment(ref _count);
 
		}
 
		//dequeue(Q: pointer to queue t, pvalue: pointer to data type): boolean
		///
		///
		///
		///
 
		/// false if unable to dequeue
		public virtual bool Dequeue(out T value)
		{
 
			//D1: loop # Keep trying until Dequeue is done
			while (true)
			{
				//D2: head = Q–>Head # Read Head
				//D3: tail = Q–>Tail # Read Tail
				//D4: next = head–>next # Read Head.ptr–>next
				Node head = this._head;
				Node tail = this._tail;
				Node next = head.next;
				Node temp;
 
				//D5: if head == Q–>Head # Are head, tail, and next consistent?
				//if (Node.ReferenceEquals(head, this._head))
				if (head == this._head)
				{
					//D6: if head.ptr == tail.ptr # Is queue empty or Tail falling behind?
					//if (Node.ReferenceEquals(head, tail))
					if (head == tail)
					{
						//D7: if next.ptr == NULL # Is queue empty?
						if (next == null)
						{
							//D8: return FALSE # Queue is empty, couldn’t dequeue
							value = default(T);
							return false;
							//D9: endif
						}
						//D10: CAS(&Q–>Tail, tail, ) # Tail is falling behind. Try to advance it
						Interlocked.CompareExchange(ref this._tail, next, tail);
						//D11: else # No need to deal with Tail
					}
					else
					{
						//# Read value before CAS, otherwise another dequeue might free the next node
						//D12: *pvalue = next.ptr–>value
						value = next.value;
						//D13: if CAS(&Q–>Head, head, ) # Try to swing Head to the next node
						temp = Interlocked.CompareExchange(ref this._head, next, head);
						//if (Node.ReferenceEquals(temp, head))
						if (temp == head)
						{
							//D14: break # Dequeue is done. Exit loop
							break;
							//D15: endif
						}
 
						//D16: endif
					}
					//D17: endif
				}
				//D18: endloop
			}
 
			Interlocked.Decrement(ref _count);
 
			//D19: free(head.ptr) # It is safe now to free the old dummy node
			//D20: return TRUE # Queue was not empty, dequeue succeeded
			return true;
 
		}
 
	}

If you are using .NET 4.0, you probably don’t need this, as TPF has a lot of great (new) synchronization primitives. But if you don’t use .NET 4, or if you really want to learn how to create a great lock-free algorithm, this is my contribution to you :)

alright!  Ending, I have an appology.

I’ve been busy the last 2 weeks on GC demos and DBP entry designs.  So my part 2 of Spatial Partitions will have to wait for my next post.  Hope you enjoy thread-safety and thus can forgive me :)

Got any questions/concerns/complains!  COMMENT BELOW!

About the author:

Jason Swearingen is Technical Director at Novaleaf Game Studios (in Bangkok Thailand).
You can reach Jason via email (jasons aat novaleaf doot coom), or twitter (@jasons_novaleaf).

Being my second post here at #AltDevBlogADay, I was going to write about the commercial viability of XNA.  However I’m just finishing up the architecture of our new spatial partitioning system, so I’ll be doing this series first, while it’s still in my head :)

Spatial Partitioning Series!

I’ll be spending the next two (or more) posts on spatial partitioning.  Starting this post is a quick survey of the spatial partitioning solutions I know most about.  If you have a favorite that I don’t mention, please do let me know in the comments!

What’s spatial partitioning?

For those of you who are not familiar with the subject, you are forgiven.  Spatial partitioning (quad trees and the such)  are not really known for being the sexiest part of game development, that honor goes towards rendering or perhaps AI.  However without a proper spatial partitioning choice, that awesome “moar bloom” being thrown at the screen runs into a brick wall trying to figure out what game objects are in the camera vs what is not.  That’s ultimately what spatial partitioning is all about:  reducing the cost of  finding objects you care about by storing objects in some sort of database that is easy to query by location.   Instead of going on-and-on about it, I’d refer the beginners to wikipedia or perhaps the excellent “Real time collision detection” book on the market (chapter 2 and 7 specifically).

A Survey of the solutions

Here’s a list of the various spatial partitioning systems that I happen to know about.  I consider myself fairly well versed in the subject, so if some guru’s happen to know of a gaping hole in my knowledge, please fill me in via the comments!

Grid

Perhaps the simplest solution, this is usually implemented via a 2 dimensional array.  3d grids are of course possible, but given that most 3d games have a generally 2d distribution, and the fact that 3d grids quickly eat your systems RAM, 2d is much, much more common.

Usage Characteristics

There are generally 2 ways of using grids:   Either each cell contains the objects who’s bounding volumes (usually sphere or box) are center positions are located in the cell, or contain all objects that touch the cell.   for the former case, the actual objects (and/or metadata) may be stored in the cell directly (allocated inline), or reference pointers are stored that point to the objects actual location.  For the Later case of each cell storing all intersections, you are restricted to the reference pointer case.

Benefits / Drawbacks

The greatest benefit of grids is their simplicity, and virtually 1:1 mapping to simple 2d arrays.  If you have a homogeneous or static world, grids may be a very excellent choice.

The greatest drawback is the inability to handle heterogeneous data: objects of various sizes and/or clumped distributions are huge problems that quickly ruin the elegance and performance of grids.

Benefits of cell inline allocation of objects is cache coherency, but since you have fixed cells allocated for the entire size of your world, you run the risk of each cell’s allocations being both too big and too small if your world’s objects are heterogeneously distributed.

A more exotic grid solutions include virtual grids, who’s backing database is a hashtable.  this reduces memory use but greatly increases the cost of queries, as multiple hash lookups need to made to find neighboring cells, plus memory fragmentation.

Grids also give good performance with dynamic objects, as due to it’s fixed-space nature, there is no re-partitioning needed (which is not true with most other solutions!)

Quad Trees

Quad trees are one of the most natural extensions of grids, and are primarily designed to overcome grid’s biggest problems: heterogeneous sizes and distributions.   In the classical case, cells are replaced with “Nodes” (cells, but reference based, not fixed allocations/alignments), and nodes with two or more objects are sub-divided until only 1 object is in each of the “leaf” nodes.

Usage Characteristics

To enable elegant node sub-division, the center position of objects are used when determining ownership.   The simple case keeps dividing down to 1 object per node, but this is not strictly necessary, and is easily customizable, though if it is more efficient for you to query against 1000 objects in 1 node or 1000 nodes, is an exercise for the reader or perhaps someone else’s #AltDevBlogADay entry =D

Benefits / Drawbacks

Narrowly targeted queries are quite elegant, as walking from the root, you may reject large branches of the tree upon the parent failing to meet the query parameters.   Broad queries however, offer fairly poor performance, of requiring deep traversals of nodes.  For programming environments with a garbage collector like .NET or Java, the reference-class overhead of the nodes is substantial and can be problematic (gc stalls when running a game is not good!).

As mentioned, the nodes are partitioned based on object centers, which is quite a large problem due to “external” objects that may potentially overlap your node-of-interest when performing collision detection.  Some exotic solutions such as storing pointers to neighboring nodes exist, but generally it’s a pain in the ass and quite weak performance for dynamic objects.  Another big weakness of trees are the need to repartition when dynamic objects move, the overhead of which can cripple highly dynamic simulations.

One potential benefit of trees is using the varied node sizes (nodes are cut in 4 each level) to bucket objects based on size.  This also helps reduce the complexity of handling overlapping nodes, but it’s still not a simple decision on how to handle this problem.  some choices push the objects up to the first node that entirely contains them, but unfortunately this tends to push a large number of objects all the way up to the root, due to objects overlapping the partition boundaries (as an example, consider an object at (0,0) in the picture shown above)

Often cited as a solution are “loose” quad trees, but I dislike these for the same reason I dislike the seemingly coolsphere-tree: maintenance is a complicated mess and it’s not so obvious how to customize the ‘looseyness’ to optimize performance in any given situation.

Another big caveat for quad trees is that they should not be used for heterogeneous distributions, as you will effectively have a cache-poor, pointer-based grid at the lowest level and a required tree-traversal on top.  Generally for heterogeneous distributions, you are better served by a grid.

Though I mention many drawbacks, trees aren’t that bad.  their memory savings compared to grids under “clustered distribution” situations is considerable, while offering fast coarse-granularity partitioning, and it’s darn simple to implement.

Hierarchy Grids

A cross between grids and a quad tree, think of it as pre-allocating all the nodes of a tree (whether they have objects in them or not).  So with the respect of  the two, they share the strengths and weaknesses of grids/trees based on these choices.  I won’t repeat them, you can simply read them above :)

Benefits / Drawbacks

Overall, I much prefer hierarchy grids over grids/trees, because the platforms I work on can afford the extra memory overhead, and it’s actually quite advantageous to pre-allocate for my platform of choice (XNA/.NET) which reduces garbage collection pressure.

The biggest drawback to this is the expensive cost of querying empty cells.

Kd Trees

kd-trees are kind of  the uber-spatial-optimization of quad trees, where instead of sub-dividing the world into fixed sized cells, the spaces are sized based on the objects located inside (at least where they were at time 0).

Usage Characteristics

Much the same as quad trees, except “faster” queries.  However special care has to be made on modifications, as fragmentation occurs and the tree will need to be rebalanced to maintain high performance.   Generally these are useful for offline pre-computation of static environments.

Benefits / Drawbacks

good for static environments (better than quad trees for localized, ray queries), but not the most trivial to implement, and is not a good choice for highly dynamic environments due to the additional costs of repartitioning.

Overall, the performance (and logic) is fairly close to quad trees. I dislike this choice because of the high repartitioning cost, and unlike a grid or quad tree, is a bit more difficult to debug.

Zones/Rooms

Some-what a ‘super partition’  strategy is to subdivide the world by “room”, often the dimensions of which are left up to content creators, and the connection of rooms performed by portals in addition to the potential for coordinate-system locality. A fairly well known example of this is the game dungeon siege.

Usage Characteristics

While I have not personally experimented with this approach, it seems interesting.  Perhaps not the way as described in dungeon siege, but I could say this approach being useful for “zones” in the world-of-warcraft sense of the word: allowing each zone to be subdivided by it’s own partitioning system.

Also noted by the dungeon siege article is that there is a certain benefit to allowing artists to author the rooms, but also there is an incredible amount of complex infrastructure and toolsets that need to be developed to undertake their approach.    I would consider this to be fairly risky, and costly, and puts an emphasis on hand-tailored content, which is a luxury none but the most AAA projects can afford.

Offset Hierarchy Grid (OHG)

The OHG is what I just finished architecting for Novaleaf’s use.  It’s a hierarchy grid, with each level offset from the previous, to allow the benefits of “loosey” grids/trees without their unpredictable nature and maintenance overhead.

Usage-wise it’s “just a grid”, so gives the same benefits and tradeoffs.  However obviously since I just architected Novaleaf’s solution around the OHG, there must be some reason we went this approach, right?   well if you are reading this far, I’m sorry to disappoint, but this will be the subject of my next blog post(s)    Complain in the comments!!!

About the author:

Jason Swearingen is Technical Director at Novaleaf Game Studios.
You can reach Jason via email (jasons aat novaleaf doot coom), or twitter (@jasons_novaleaf).

PS: images courtesy of wikipedia

PPS: anything you want to know about in detail?  again, let me know in the comments!!!

Before I go further, A bit of a disclaimer:  

Nobody gives a shit!

My Introspections, in no particular order:

Having industry connections help.  

Business Matching Events:

Conclusions

So in summary:  Most publishers are narcissistic ruthless cutthroats, only interested in reducing risk and making money.  A fact we already know, right?

About the author:

Jason Swearingen is Technical Director at Novaleaf Game Studios.
You can reach Jason via email (jasons aat novaleaf doot coom), or twitter (@jasons_novaleaf).
Additional Novaleaf blogs team can be found here.