Concurrency Concerns on Android

Managing concurrency in Android Development using the SDK

Concurrency Concerns on Android

The eeGeo SDK uses OpenGL. Android best practices recommend OpenGL rendering occurs on a background thread, and this is the pattern we apply.

This introduces concurrency concerns when your application needs to interact with the eeGeo SDK C++ types on Android. This section deals recommends patterns and practices for dealing with the Android Concurrency Concerns.

In this section:

Concurrency Introduction

On Android only, the eeGeo SDK C++ Types are ‘running’ on an “background render thread”. Your Application UI in Java is running on the “Main UI Thread”. This introduces threading concerns on Android which can cause issues if not modelled adequately.


Android recommendations OpenGL rendering is performed on a background thread, please see GLSurfaceView documentation for more details.

Application Developers on Android must be aware of these concurrency concerns – as almost all types in the eeGeo SDK do not make any thread-safety guarantees.

We provide a number of recommendations, patterns and practices that we suggest reading and understanding before undertaking significant Android development. As an aid, we provide a fully-featured example application that correctly models the concurrency concerns on Android.

Java Runnables

An approach that can be taken when working in Java code is the use of two Activity Helpers: runOnUiThread and runOnNativeThread.

runOnUiThread takes a Java Runnable, and will queue the Runnable to be executed on the UI Thread. Conversely, runOnNativeThread, queues the Runnable and will execute it as soon as it can on the Native thread.

runOnUiThread can be used if you need make notifications from SDK types in C++ to your Java UI: You can make a JNI call from C++ -> Java, then call Activity runOnUiThread to ensure the operation runs on the UI thread. An example of this can be seen in which is called by PositionJavaPinButtonExample.cpp

runOnNativeThread can be used if you need to call C++ SDK types from events occurring in your UI. You can call Activity runOnNativeThread from your UI event handlers, and in the Runnable make a JNI call to safely call into C++ from the Native thread. An example of this can be seen in which calls AndroidRouteSimulationProxy.cpp

The use of these helpers will require knowledge of Java/C++ Interop using the JNI. More information can be found in the Interaction with a native Android UI documentation. A combination of runOnUIThread / runOnNativeThread and Java<->C++ Interop using the JNI will allow you to write a correct Concurrency Model.

This is our recommended approach where there a very small amount of Application-level C++ code majority of Application is in Java.

C++ Message Buses

The ability to manage concurrency in C++ is also available via MPMCMessageBus<T> to enable thread-safe message passing and/or eventing on Android. This approach is used extensively in mobile-example-app.

MPMCMessageBus&ltT&gt provides a thread-safe MessageBus – enabling Subscribers to called at a well known point, and Publishing of messages to occur from any thread via a concurrent queue.

mobile-example-app makes use of this via BidirectionalBus – this uses two catalogs of messages (Native to UI messages, and UI to Native messages) that model the concurrency concern in that application between both threads.

This is our recommended approach where there is a significant volume of Application-level code in C++ code and the concurrency concern can be modelled in C++ on both sides of the concurrency boundary. In this way, the number of JNI/C++ Interops can be reduced to just changing view state & receiveing view events.

POSIX / Java Synchronisation Primitives

POSIX Synchronisation Primitives are available via the Android NDK. Additionally, Java also provides synchronization primitives and higher level concurrency-friendly containers.

An example of using pthread_mutex can be found in ShowJavaPlaceJumpUIExample.cpp

The eeGeo SDK provides no fixed mechanism for managing concurrency concerns on Android: as an application developer you can chose the most appropriate solution for your application’s needs.

However, for most application developers, we strongly recommend using either the Java Runnable and/or C++ Message Bus infrastructure mentioned in the two sections above and avoiding managing concurrency yourself via low-level synchronisation primitives.

If you are not sure, you can base your solution off mobile-example-app.

mobile-example-app Concurrency Model

We provide a fully-featured example application built ontop of the eeGeo SDK at eegeo/mobile-example-app. This application is Open Source under the eeGeo SDK Evaluation License.

This example app is cross-platform on iOS and Android, with a significant portion of the application code in portable C++. The concurrency concern is explicitly modelled using the C++ Message Bus pattern covered in this document. We hope mobile-example-app provides a useful starting point for your Android developent and as a reference implementation for the concurrency concerns encounterable on Android.

For further reading, we also provide a more detailed exploration of the concurrency concerns in mobile-example-app