Real-Time API v4.2.2

This page describes how to make use of the real-time extension in your Android applications.
Please set up the development environment to work for Windows and Linux first by following this guide.

Declaring Real-Time Applications


This section describes how to declare applications such that the Android system is able to identify them as real-time applications. It does not mean that the application will run with real-time priority, but it will prevent the system from killing the application (during a long-term operation or in dangerous out-of-memory situations). Developers may flag whole applications or just selected components to be persistent using the flag <meta-data android:name=”realtime-flag” android:value=”true” /> in the manifest file.

The following manifest file belongs to an application with two activities and two services.

<manifest>
 <application>
    <activity android:name=".Activity1" />

    <activity android:name=".Activity2">
      <meta-data android:name="realtime-flag" android:value="true" />
    </activity>

    <service android:name=".Service1" android:process=":ServiceProcess">
      <meta-data android:name="realtime-flag" android:value="true" />
    </service>  

    <service android:name=".Service2" />
  </application>
</manifest>

As soon as one component of an application process is marked as real-time, all other components of the same process will implicitly be treated real-time. In the example above the main process (encapsulating both activites and the second service), as well as the separated process for the first service are marked as real-time. All application components can be marked as real-time at once by adding the tag to the <application> tag of the manifest file:

<manifest>
  <application>
    <meta-data android:name="realtime-flag" android:value="true" />
  </application>
</manifest>

 

Setting Real-Time Priority


Independently of the real-time flag, priority of single application threads can be raised to real-time values. For this purpose, first import the following packages:

import rtandroid.IRealTimeService;
import rtandroid.RealTimeWrapper;

Add the following line to your manifest file in order to authorize the application to use the real-time priority:

<uses-permission android:name="android.permission.USE_RT_PRIORITY"/>

Execute the following commands to raise the priority of the calling thread to real-time:

int prio = 60; // priority value between RT_THREAD_MIN_PRIORITY and RT_THREAD_MAX_PRIORITY
int tid = android.os.Process.myTid();
IRealTimeService service = RealTimeWrapper.getService();
service.setSchedulingPolicy(tid, RealTimeWrapper.SCHED_POLICY_FIFO);
service.setPriority(tid, prio);

 

Setting CPU Affinity


In order to save/extend battery power, Android reduces the CPU power consumption whenever the device load is low or the display is turned off. This is problematic for applications which require deterministic execution. RTAndroids API offers the CpuLock class, which allows you to lock the CPU to a certain power level.

In order to use the lock, first import the following class:

import rtandroid.CpuLock;

Add the following line to your manifest file in order to authorize the application to use the lock:

<uses-permission android:name="android.permission.USE_RT_PRIORITY"/>

When creating a CPU lock, the Context of the current application and the desired CPU power level has to be specified. See the following example:

CpuLock lock = new CpuLock(context);
cpuLock.setPowerLevel(powerLevel); // power level between 1 and 100
lock.acquire(); // acquire the lock, the CPU power level is now held

For releasing the lock, the class provides the release() method:

lock.release();

The invocation of this method will return the control of the CPU power level to Android.