6.13 Developing Thread Safe Extensions

In this document we are going to discuss the threading architecture in SmartFoxServer and how to write thread-safe extensions using Java, ActionScript and Python.
Developers coming from a Java or Python background should already be familiar with multithread programming, while ActionScript coders would probably be less used to these concepts.

If you are interested in learning more we suggest to consult these external resources:

• IBM article on multithreading
• Quick overview of multithreading
• Programming Java Threads

» SmartFoxServer architecture overview

The following diagram shows a simplified view of the internal architecture of the server:



From the Server Core the incoming socket data is initially validated and assembled into messages. We're going to refer to these incoming messages as requests. Once we have a valid request we dispatch it to one of the two main request handlers:

• System Handler: it is responsible for handling default requests such as "createRoom", "joinRoom", "sendPublicMessage" etc...
• Extension Handler: manages requests for all the active extensions in the server.

Both controllers shown in the left side of the diagram use a blocking queue and a thread pool to accomplish their work: this means that each request is enqueued as soon as it is passed to the controller and its worker threads will process them in the order they arrived.

It is important to note that by default both controllers use a single thread even if the server design implements a thread-pool: this is done to avoid running too many processes on a single CPU. Additional workers can be added if your hardware permits it (i.e. runs multiple dual/quad core CPUs), taking full advantage of parallel processing. All you have to do is simply edit a few lines in the main XML server configuration.

The Event Writer on the right side of the diagram is responsible for writing data back to the clients, and works similarly to the input controllers: outgoing messages are piled up into the output queue and its worker threads will process them in order.
The Event Writer uses one thread by default, but we usually recommend to increase this number if you're running a multi-core/multi-cpu system. This stage of the server is usually quite busy especially when broadcasting events to a large number of clients simultaneously, for this reason the controller can benefit from multiple threads.

Finally the Event Writer is not going to affect thread safety in extension development, but we have added it in the diagram for completeness.

» Extension thread safety

After examining the server design we can now concentrate on how it can affect thread safety in our extension code.

The following is a skeleton of a typical SmartFoxServer extension in Java:

public class ExtensionTemplate extends AbstractExtension
{
	public void init()
	{
		trace("Extension initialized");
	}

	public void destroy()
	{
		trace("Extension destroyed");
	}

	public void handleRequest(String cmd, ActionscriptObject ao, User u, int fromRoom)
	{
		// Your code here
	}

	public void handleInternalEvent(InternalEventObject ieo)
	{
		// Your code here
	}
	
	...
	...
}

function init()
{
	trace("Extension initialized")
}

function destroy()
{
	trace("Extension destroyed")
}

function handleRequest(cmd, params, user, fromRoom)
{
	// Add your code here
}

function handleInternalEvent(evt)
{
	// Add your code here
}

def init():
	_server.trace("Python extension starting")


def destroy():
	_server.trace("Python extension stopping")


def handleRequest(cmd, params, who, roomId, protocol):
	pass


def handleInternalEvent(evt):
	pass	

In the diagram below you can see how the server controllers will invoke methods on your extensions:

From what we can see at least two different threads are going to invoke methods on the extension: the handleRequest method is always called by the Extension Handler while most of the internal events are fired by the System Handler. Actually some of the disconnection events can also be fired by the Connection Cleaner classes which run their own thread.

We also need to mention the Scheduler class that was introduced in SmartFoxServer 1.6 which simplifies the process of running time-based events and the handlInternalRequest method that allows any object inside the server (including the embedded http-server) to call the extension code.

To sum it all up: even in the simplest extension we have at least 2 different threads calling our code.
This implies that we need to make sure that access to globally shared data is performed in a thread-safe way.

Here are a few suggestion for common thread-safe access to data:

• Shared collections (Sets, Lists, Maps...): Java 5 introduced a series of powerful thread-safe collections such as ConcurrentHashMap, BlockingQueue, CopyOnWriteArrayList etc... We highly recommend to invest some time in learning these new classes as they are great time-savers and offer high performance.
  To learn more check these pages:
  
  » Java 5 Collections
  » Concurrent Collections


• Custom properties in Room and User objects: both the Room and User classes offer a simple mechanism for storing custom values by exposing a public properties member of type Map. By default the server uses an HashMap implementation which is not thread safe, so you will have to properly synchronize the accesses.
  
  Starting from SmartFoxServer 1.6 we have introduced a new configuration parameter called <DynamicPropertiesClass> which allows to specify which class (extending java.util.Map) we want to use, for example: java.util.concurrent.ConcurrentHashMap


• Database access: the SmartFoxServer DbManager class already implements thread-safe access so you don't have to worry about it.


• Shared files: in case your application works with streams that are referenced globally (and accessed in both handleRequest and handleInternalEvent) we suggest to make sure that all accesses are properly synchronized.


• Custom threads: there is no particular problem with running your own threads in the extension code, just make sure to shut them down in the destroy() method of your extension. Forgetting about this can lead to unexpected behaviors and memory leaks.

» Server framework thread safety

Most of the SmartFoxServer Java framework is accessed through the ExtensionHelper class which exposes methods for creating and removing rooms, access the buddy list and database and much more... All these methods are already thread safe unless differently specified.

» Thread safety using ActionScript and Python

The scripting languages available with the SmartFoxServer framework are Java implementations that run in the JVM together with the other server classes. The scripts are compiled into Java byte-code at runtime and are subject to the same threading rules described in this document. Thread safety is already encapsulated in these language implementations so you should be able to use the ActionScript or Python objects and native collections without worries.
There are however a few cases where concurrent access to a shared resource should be tested to avoid problems when in production: for example the access to physical resources such as files and external network connections.

Advanced developers can also take advantage of the JVM environment to access the Java framework, the other currently loaded objects or their custom classes. When working with Java classes always make sure that they are thread safe as the scripting languages don't provide any construct that is similar to the synchronized keyword in Java. In the case of custom classes it is highly recommended to encapsulate all the synchronization details in your Java code.
Finally we also recommended to take a look at the Java 5 (and Java 6) concurrent collections (mentioned earlier in this article) which provide even better performance than the native collections found in ActionScript and Python.