Concurrency

Classes
class	xmog_lock_holder
	A utility class used for synchronizing access to a Java object. More...
class	xmog_thread_factory
	A class to launch threads in a platform-portable manner. More...

Detailed Description

Overview

In general, the runtime API is thread- and hyperthread-safe, but that statement has to be taken with a grain of salt. There are many things that you could do to cause problems and there are also some very easy strategies you can use to avoid concurrency-related problems.

If you have some familiarity with JNI, you can probably forget most of your hard-earned experience. The runtime automatically takes care of:

• attaching a thread to the JVM when required (you can do it manually via xmog_jvm::attach())
• detaching the thread from the JVM when it exits (you can do it manually via xmog_jvm::detach() or xmog_jvm::static_detach())
• managing JNI references so that they're usable on multiple threads

While the runtime does a lot of the heavy lifting for you, you should not be completely unaware of things to do and things not to do in the area of concurrency.

Things to do

1. Make sure your application is built using proper compiler and linker options

   Many compilers and platforms allow you to build applications that perform better when you use singlethreaded runtime libraries and options. Never forget that the runtime library will typeically launch a JVM which is almost always multithreaded. Consult your compiler manuals on the proper settings for multithreaded applications and use those settings.

2. Initialize the framework at a well-defined point

   You can make your life much easier if you load the JVM or connect to the shared JVM in a function that you call from your main() function. This allows you to avoid initialization race conditions between different worker threads that try to kick off a JVM or a connection. It also gives you a chance to handle initialization failure in a well-defined and consistent manner.

3. Use external synchronization if you ABSOLUTELY HAVE TO share an object between threads

   You should be able to dereference one proxy object on multiple threads, but if you have to make assignments to the object, you need to synchronize access to it or use multiple objects referencing the same Java object.

Things to avoid

1. Don't assign to one proxy object from multiple threads

   To keep performance good, we do not safe-guard access to proxy objects. This means that an assignment of a proxy object to another proxy object exhibits a race condition. You can avoid this race condition by using different proxy instances on different threads. Just to clarify: the same Java object can be referenced by multiple C++ proxy objects. It is easy to create another C++ proxy instance that references the same Java object as an already existing C++ proxy instance; all you need to do is call the copy constructor. Now you can safely use one instance on one thread and the other instance on another thread.

   Don't forget that you might still have synchronization issues on the Java side! It is only safe to use proxies from multiple C++ threads if it is safe to use the underlying Java object from multiple Java threads.