Support WorkManager tasks

The androidx WorkManager component allows simple handling of tasks in
Android apps. Furthermore, in Android 12, WorkManager tasks are the
preferred way to run foreground services when the app is in the
background.

Since the python interpreter integration only allows running one python
interpreter per process, this uses a `RemoteListenableWorker` to run the
tasks on a service in a separate process. Unfortunately, that's only
available since the work-multiprocess 2.6.0 release, which requires SDK
30.

Co-authored-by: Robert Niederreiter <[email protected]>
Co-authored-by: Philipp Auersperg <[email protected]>

Author: 3 people

pythonforandroid/bootstraps/common/build/build.py

@@ -494,6 +494,39 @@ def make_package(args):
             base_service_class=base_service_class,
         )
 
+    worker_names = []
+    for spec in args.workers:
+        spec = spec.split(':')
+        name = spec[0]
+        entrypoint = spec[1]
+
+        worker_names.append(name)
+        worker_target_path = \
+            'src/main/java/{}/{}Worker.java'.format(
+                args.package.replace(".", "/"),
+                name.capitalize()
+            )
+        render(
+            'Worker.tmpl.java',
+            worker_target_path,
+            name=name,
+            entrypoint=entrypoint,
+            args=args,
+        )
+
+        worker_service_target_path = \
+            'src/main/java/{}/{}WorkerService.java'.format(
+                args.package.replace(".", "/"),
+                name.capitalize()
+            )
+        render(
+            'WorkerService.tmpl.java',
+            worker_service_target_path,
+            name=name,
+            entrypoint=entrypoint,
+            args=args,
+        )
+
     # Find the SDK directory and target API
     with open('project.properties', 'r') as fileh:
         target = fileh.read().strip()
@@ -510,6 +543,15 @@ def make_package(args):
         sdk_dir = fileh.read().strip()
     sdk_dir = sdk_dir[8:]
 
+    # Specific WorkManager versions require newer SDK versions.
+    #
+    # See https://developer.android.com/jetpack/androidx/releases/work
+    # for details.
+    if int(android_api) >= 31:
+        work_manager_version = '2.7.1'
+    else:
+        work_manager_version = '2.6.0'
+
     # Try to build with the newest available build tools
     ignored = {".DS_Store", ".ds_store"}
     build_tools_versions = [x for x in listdir(join(sdk_dir, 'build-tools')) if x not in ignored]
@@ -541,6 +583,7 @@ def make_package(args):
         "args": args,
         "service": service,
         "service_names": service_names,
+        "worker_names": worker_names,
         "android_api": android_api,
         "debug": "debug" in args.build_mode,
         "native_services": args.native_services
@@ -572,6 +615,7 @@ def make_package(args):
         build_tools_version=build_tools_version,
         debug_build="debug" in args.build_mode,
         is_library=(get_bootstrap_name() == 'service_library'),
+        work_manager_version=work_manager_version,
         )
 
     # gradle properties
@@ -797,6 +841,9 @@ def create_argument_parser():
     ap.add_argument('--service', dest='services', action='append', default=[],
                     help='Declare a new service entrypoint: '
                          'NAME:PATH_TO_PY[:foreground]')
+    ap.add_argument('--worker', dest='workers', action='append', default=[],
+                    help='Declare a new worker entrypoint: '
+                         'NAME:PATH_TO_PY')
     ap.add_argument('--native-service', dest='native_services', action='append', default=[],
                     help='Declare a new native service: '
                          'package.name.service')
@@ -1048,6 +1095,11 @@ def _read_configuration():
               '--launcher (SDL2 bootstrap only)' +
               'to have something to launch inside the .apk!')
         sys.exit(1)
+
+    if args.workers and not args.enable_androidx:
+        print('WARNING: Enabling androidx for worker support')
+        args.enable_androidx = True
+
     make_package(args)
 
     return args

pythonforandroid/bootstraps/common/build/jni/application/src/start.c

@@ -422,6 +422,29 @@ JNIEXPORT int JNICALL Java_org_kivy_android_PythonService_nativeStart(
                               true);
 }
 
+JNIEXPORT int JNICALL Java_org_kivy_android_PythonWorker_nativeStart(
+    JNIEnv *env,
+    jobject thiz,
+    jstring j_android_private,
+    jstring j_android_argument,
+    jstring j_service_entrypoint,
+    jstring j_python_name,
+    jstring j_python_home,
+    jstring j_python_path,
+    jstring j_arg) {
+  LOGP("Entering org.kivy.android.PythonWorker.nativeStart");
+  return native_service_start(env,
+                              thiz,
+                              j_android_private,
+                              j_android_argument,
+                              j_service_entrypoint,
+                              j_python_name,
+                              j_python_home,
+                              j_python_path,
+                              j_arg,
+                              false);
+}
+
 #if defined(BOOTSTRAP_NAME_WEBVIEW) || defined(BOOTSTRAP_NAME_SERVICEONLY)
 // Webview and service_only uses some more functions:
 

pythonforandroid/bootstraps/common/build/src/main/java/org/kivy/android/PythonWorker.java

@@ -0,0 +1,130 @@
+package org.kivy.android;
+
+import android.content.Context;
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+import androidx.concurrent.futures.CallbackToFutureAdapter.Completer;
+import androidx.concurrent.futures.CallbackToFutureAdapter;
+import androidx.work.ListenableWorker.Result;
+import androidx.work.multiprocess.RemoteListenableWorker;
+import androidx.work.Worker;
+import androidx.work.WorkerParameters;
+
+import com.google.common.util.concurrent.ListenableFuture;
+
+import java.io.File;
+import java.lang.System;
+import java.util.concurrent.Executors;
+
+import org.kivy.android.PythonUtil;
+
+public class PythonWorker extends RemoteListenableWorker {
+    private static final String TAG = "PythonWorker";
+
+    // WorkRequest data key for python service argument
+    public static final String ARGUMENT_SERVICE_ARGUMENT = "PYTHON_SERVICE_ARGUMENT";
+
+    // Python environment variables
+    private String androidPrivate;
+    private String androidArgument;
+    private String pythonName;
+    private String pythonHome;
+    private String pythonPath;
+    private String workerEntrypoint;
+
+    public PythonWorker(
+        @NonNull Context context,
+        @NonNull WorkerParameters params) {
+        super(context, params);
+
+        String appRoot = PythonUtil.getAppRoot(context);
+
+        androidPrivate = appRoot;
+        androidArgument = appRoot;
+        pythonHome = appRoot;
+        pythonPath = appRoot + ":" + appRoot + "/lib";
+
+        File appRootFile = new File(appRoot);
+        PythonUtil.unpackAsset(context, "private", appRootFile, false);
+        PythonUtil.loadLibraries(
+            appRootFile,
+            new File(getApplicationContext().getApplicationInfo().nativeLibraryDir)
+        );
+    }
+
+    public void setPythonName(String value) {
+        pythonName = value;
+    }
+
+    public void setWorkerEntrypoint(String value) {
+        workerEntrypoint = value;
+    }
+
+    @Override
+    public ListenableFuture<Result> startRemoteWork() {
+        return CallbackToFutureAdapter.getFuture(completer -> {
+            String dataArg = getInputData().getString(ARGUMENT_SERVICE_ARGUMENT);
+            final String serviceArg;
+            if (dataArg != null) {
+                Log.d(TAG, "Setting python service argument to " + dataArg);
+                serviceArg = dataArg;
+            } else {
+                serviceArg = "";
+            }
+
+            // If the work is cancelled, exit the whole process since we
+            // have no other way to stop the python thread.
+            //
+            // FIXME: Unfortunately, exiting here causes the service to
+            // behave unreliably since all the connections are not
+            // unbound. Android will immediately restart the service to
+            // bind the connection again and eventually there are issues
+            // with the process not exiting to completely clear the
+            // Python environment.
+            completer.addCancellationListener(new Runnable() {
+                @Override
+                public void run() {
+                    Log.i(TAG, "Exiting remote work service process");
+                    System.exit(0);
+                }
+            }, Executors.newSingleThreadExecutor());
+
+            // The python thread handling the work needs to be run in a
+            // separate thread so that future can be returned. Without
+            // it, any cancellation can't be processed.
+            final Thread pythonThread = new Thread(new Runnable() {
+                @Override
+                public void run() {
+                    int res = nativeStart(
+                        androidPrivate, androidArgument,
+                        workerEntrypoint, pythonName,
+                        pythonHome, pythonPath,
+                        serviceArg
+                    );
+                    Log.d(TAG, "Finished remote python work: " + res);
+
+                    if (res == 0) {
+                        completer.set(Result.success());
+                    } else {
+                        completer.set(Result.failure());
+                    }
+                }
+            });
+            pythonThread.setName("python_worker_thread");
+
+            Log.i(TAG, "Starting remote python work");
+            pythonThread.start();
+
+            return TAG + " work thread";
+        });
+    }
+
+    // Native part
+    public static native int nativeStart(
+        String androidPrivate, String androidArgument,
+        String workerEntrypoint, String pythonName,
+        String pythonHome, String pythonPath,
+        String pythonServiceArgument
+    );
+}

pythonforandroid/bootstraps/common/build/templates/Worker.tmpl.java

@@ -0,0 +1,45 @@
+package {{ args.package }};
+
+import android.content.Context;
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+import androidx.work.Data;
+import androidx.work.WorkRequest;
+import androidx.work.WorkerParameters;
+
+import org.kivy.android.PythonWorker;
+
+public class {{ name|capitalize }}Worker extends PythonWorker {
+    private static final String TAG = "{{ name|capitalize }}Worker";
+
+    public static {{ name|capitalize }}Worker mWorker = null;
+
+    public {{ name|capitalize }}Worker (
+        @NonNull Context context,
+        @NonNull WorkerParameters params) {
+        super(context, params);
+        setPythonName("{{ name }}");
+        setWorkerEntrypoint("{{ entrypoint }}");
+        mWorker = this;
+    }
+
+    public static Data buildInputData (String serviceArgument) {
+        String dataArgument = serviceArgument == null ? "" : serviceArgument;
+        Data data = new Data.Builder()
+            .putString(ARGUMENT_SERVICE_ARGUMENT, dataArgument)
+            .putString(ARGUMENT_PACKAGE_NAME, "{{ args.package }}")
+            .putString(ARGUMENT_CLASS_NAME,
+                       {{ name|capitalize }}WorkerService.class.getName())
+            .build();
+        Log.v(TAG, "Request data: " + data.toString());
+        return data;
+    }
+
+    public static WorkRequest buildWorkRequest (
+        WorkRequest.Builder builder,
+        String serviceArgument) {
+        Data data = buildInputData(serviceArgument);
+        return builder.setInputData(data).build();
+    }
+}

pythonforandroid/bootstraps/common/build/templates/WorkerService.tmpl.java

@@ -0,0 +1,41 @@
+package {{ args.package }};
+
+import android.content.Context;
+import android.util.Log;
+
+import androidx.work.Configuration;
+import androidx.work.multiprocess.RemoteWorkerService;
+import androidx.work.WorkManager;
+
+import java.lang.System;
+
+public class {{ name|capitalize }}WorkerService extends RemoteWorkerService {
+    private static final String TAG = "{{ name|capitalize }}WorkerService";
+
+    @Override
+    public void onCreate() {
+        try {
+            Log.v(TAG, "Initializing WorkManager");
+            Context context = getApplicationContext();
+            Configuration configuration = new Configuration.Builder()
+                .setDefaultProcessName(context.getPackageName())
+                .build();
+            WorkManager.initialize(context, configuration);
+        } catch (IllegalStateException e) {
+        }
+        super.onCreate();
+    }
+
+    @Override
+    public void onDestroy() {
+        super.onDestroy();
+
+        // The process needs to exit when the service is destroyed since
+        // p4a doesn't support starting a Python interpreter more than
+        // once per process. Combined with the stopWithTask="true"
+        // configuration in the manifest, this should ensure that the
+        // service process exits when a task completes.
+        Log.v(TAG, "Exiting service process");
+        System.exit(0);
+    }
+}

pythonforandroid/bootstraps/common/build/templates/build.tmpl.gradle

@@ -101,6 +101,9 @@ android {
         main {
             jniLibs.srcDir 'libs'
             java {
+                {% if not args.enable_androidx %}
+                exclude 'org/kivy/android/PythonWorker.java'
+                {% endif %}
 
                 {%- for adir, pattern in args.extra_source_dirs -%}
                     srcDir '{{adir}}'
@@ -128,10 +131,16 @@ dependencies {
     implementation '{{ depend }}'
     {%- endfor %}
     {%- endif %}
-    {% if args.presplash_lottie %}
+    {%- if args.presplash_lottie %}
     implementation 'com.airbnb.android:lottie:3.4.0'
     {%- endif %}
     implementation 'com.android.support:support-v4:26.1.0'
     implementation 'com.android.support:multidex:1.0.3'
+    {%- if args.workers %}
+    implementation 'androidx.annotation:annotation:1.3.0'
+    implementation 'androidx.concurrent:concurrent-futures:1.1.0'
+    implementation 'androidx.work:work-runtime:{{ work_manager_version }}'
+    implementation 'androidx.work:work-multiprocess:{{ work_manager_version }}'
+    {%- endif %}
 }
 

pythonforandroid/bootstraps/sdl2/build/templates/AndroidManifest.tmpl.xml

@@ -119,6 +119,12 @@
         {% for name in native_services %}
         <service android:name="{{ name }}" />
         {% endfor %}
+        {% for name in worker_names %}
+        <service android:name="{{ args.package }}.{{ name|capitalize }}WorkerService"
+                 android:process=":worker_{{ name }}"
+                 android:exported="false"
+                 android:stopWithTask="true" />
+        {% endfor %}
 
         {% if args.billing_pubkey %}
         <service android:name="org.kivy.android.billing.BillingReceiver"

pythonforandroid/bootstraps/service_library/build/templates/AndroidManifest.tmpl.xml

@@ -13,6 +13,12 @@
                  android:process=":service_{{ name }}"
                  android:exported="true" />
         {% endfor %}
+        {% for name in worker_names %}
+        <service android:name="{{ args.package }}.{{ name|capitalize }}WorkerService"
+                 android:process=":worker_{{ name }}"
+                 android:exported="false"
+                 android:stopWithTask="true" />
+        {% endfor %}
     </application>
 
 </manifest>