Add RootArgs class and enhance RootOptions and RootThread for custom argument handling

DerGoogler · DerGoogler · commit 9b03e4eaa1f7 · 2026-04-01T17:57:44.000+02:00
diff --git a/thread/src/main/java/dev/mmrlx/thread/RootArgs.java b/thread/src/main/java/dev/mmrlx/thread/RootArgs.java
@@ -0,0 +1,132 @@
+package dev.mmrlx.thread;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * A typed, serializable container for custom arguments that are passed alongside a
+ * {@link RootCallable} and survive the cross-process boundary.
+ *
+ * <p>All values must be serializable by Kryo (e.g. primitives, {@link String},
+ * {@link java.io.Serializable} objects, or {@link android.os.Parcelable} types).
+ *
+ * <h3>Example</h3>
+ * <pre>{@code
+ * RootArgs args = RootArgs.of("path", "/data/local/tmp/test.txt")
+ *                         .with("overwrite", true);
+ *
+ * RootThread.submit(options -> {
+ *     String path = options.getArgs().get("path");
+ *     boolean overwrite = options.getArgs().get("overwrite", false);
+ *     // …
+ *     return null;
+ * }, args);
+ * }</pre>
+ */
+public final class RootArgs implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /** Shared empty instance; avoids allocations when no args are needed. */
+    public static final RootArgs EMPTY = new RootArgs(Collections.emptyMap());
+
+    private final Map<String, Object> mArgs;
+
+    private RootArgs(@NonNull Map<String, Object> args) {
+        mArgs = args;
+    }
+
+    /**
+     * Creates a new {@code RootArgs} with a single key-value pair.
+     *
+     * @param key   The argument name.
+     * @param value The argument value; must be Kryo-serializable.
+     */
+    @NonNull
+    public static RootArgs of(@NonNull String key, @Nullable Object value) {
+        Map<String, Object> map = new HashMap<>();
+        map.put(key, value);
+        return new RootArgs(map);
+    }
+
+    /**
+     * Creates a new {@code RootArgs} from an existing map.
+     *
+     * @param args Key-value pairs; the map is copied defensively.
+     */
+    @NonNull
+    public static RootArgs of(@NonNull Map<String, ?> args) {
+        return new RootArgs(new HashMap<>(args));
+    }
+
+    /**
+     * Returns a new {@code RootArgs} with the given key-value pair added (or replaced).
+     */
+    @NonNull
+    public RootArgs with(@NonNull String key, @Nullable Object value) {
+        Map<String, Object> copy = new HashMap<>(mArgs);
+        copy.put(key, value);
+        return new RootArgs(copy);
+    }
+
+    /**
+     * Returns the value associated with {@code key}, or {@code null} if absent.
+     *
+     * @param key The argument name.
+     * @param <T> The expected type.
+     */
+    @Nullable
+    @SuppressWarnings("unchecked")
+    public <T> T get(@NonNull String key) {
+        return (T) mArgs.get(key);
+    }
+
+    /**
+     * Returns the value associated with {@code key}, or {@code defaultValue} if absent.
+     *
+     * @param key          The argument name.
+     * @param defaultValue Fallback if the key is not present.
+     * @param <T>          The expected type.
+     */
+    @SuppressWarnings("unchecked")
+    public <T> T get(@NonNull String key, @NonNull T defaultValue) {
+        Object value = mArgs.get(key);
+        return value != null ? (T) value : defaultValue;
+    }
+
+    /**
+     * Returns {@code true} if an argument with the given key exists.
+     */
+    public boolean has(@NonNull String key) {
+        return mArgs.containsKey(key);
+    }
+
+    /**
+     * Returns an unmodifiable view of all argument keys.
+     */
+    @NonNull
+    public Set<String> keys() {
+        return Collections.unmodifiableSet(mArgs.keySet());
+    }
+
+    /**
+     * Returns {@code true} if no arguments are stored.
+     */
+    public boolean isEmpty() {
+        return mArgs.isEmpty();
+    }
+
+    @NonNull
+    @Override
+    public String toString() {
+        return "RootArgs" + mArgs;
+    }
+}
diff --git a/thread/src/main/java/dev/mmrlx/thread/RootOptions.java b/thread/src/main/java/dev/mmrlx/thread/RootOptions.java
@@ -10,14 +10,19 @@
  * Represents the configuration options for root-related operations within the threading framework.
  * <p>
  * This class encapsulates necessary dependencies and environment settings, such as the
- * {@link Context}, required for executing tasks that interact with the system at a root level.
+ * {@link Context} and any custom {@link RootArgs}, required for executing tasks that interact
+ * with the system at a root level.
  */
 public class RootOptions {
     @NonNull
     private final Context mContext;
 
-    RootOptions(@NonNull Context context) {
+    @NonNull
+    private final RootArgs mArgs;
+
+    public RootOptions(@NonNull Context context, @NonNull RootArgs args) {
         mContext = context;
+        mArgs = args;
     }
 
     /**
@@ -29,4 +34,13 @@ public class RootOptions {
     public Context getContext() {
         return mContext;
     }
+
+    /**
+     * Returns the custom arguments that were supplied when the callable was submitted.
+     * Returns {@link RootArgs#EMPTY} if no arguments were provided.
+     */
+    @NonNull
+    public RootArgs getArgs() {
+        return mArgs;
+    }
 }
diff --git a/thread/src/main/java/dev/mmrlx/thread/RootThread.java b/thread/src/main/java/dev/mmrlx/thread/RootThread.java
@@ -26,6 +26,8 @@
 import org.objenesis.strategy.StdInstantiatorStrategy;
 
 import java.io.IOException;
+import java.io.Serial;
+import java.io.Serializable;
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
@@ -159,7 +161,24 @@ private static ClassResolver getAppClassResolver() {
      */
     @NonNull
     public static <T> Future<T> submit(@NonNull RootCallable<T> callable) {
-        return sExecutor.submit(() -> executeSync(callable));
+        return submit(callable, RootArgs.EMPTY);
+    }
+
+    /**
+     * Submits {@code callable} together with {@code args} to the root process and returns a
+     * {@link Future} that resolves with the callable's return value.
+     *
+     * <p>The supplied {@code args} are serialized alongside the callable and are available
+     * inside the root process via {@link RootOptions#getArgs()}.
+     *
+     * @param callable The closure to execute in the root process.
+     * @param args     Custom arguments to pass to the callable; must be Kryo-serializable.
+     * @param <T>      Return type of the callable.
+     * @return A {@link Future} representing the pending result.
+     */
+    @NonNull
+    public static <T> Future<T> submit(@NonNull RootCallable<T> callable, @NonNull RootArgs args) {
+        return sExecutor.submit(() -> executeSync(callable, args));
     }
 
     /**
@@ -175,8 +194,26 @@ public static <T> Future<T> submit(@NonNull RootCallable<T> callable) {
     @Nullable
     public static <T> T executeBlocking(@NonNull RootCallable<T> callable)
             throws IOException, InterruptedException {
+        return executeBlocking(callable, RootArgs.EMPTY);
+    }
+
+    /**
+     * Submits {@code callable} together with {@code args} to the root process and blocks the
+     * calling thread until the result is available.  Must NOT be called on the main thread.
+     *
+     * @param callable The closure to execute in the root process.
+     * @param args     Custom arguments available in the root process via
+     *                 {@link RootOptions#getArgs()}.
+     * @param <T>      Return type of the callable.
+     * @return The value returned by the callable.
+     * @throws IOException          If IPC serialisation, transport, or the remote call fails.
+     * @throws InterruptedException If the calling thread is interrupted while waiting.
+     */
+    @Nullable
+    public static <T> T executeBlocking(@NonNull RootCallable<T> callable, @NonNull RootArgs args)
+            throws IOException, InterruptedException {
         try {
-            return submit(callable).get();
+            return submit(callable, args).get();
         } catch (ExecutionException e) {
             Throwable cause = e.getCause();
             if (cause instanceof IOException) throw (IOException) cause;
@@ -202,9 +239,34 @@ public static <T> T executeBlocking(
             @NonNull RootCallable<T> callable,
             long timeout,
             @NonNull TimeUnit unit
+    ) throws IOException, InterruptedException, TimeoutException {
+        return executeBlocking(callable, RootArgs.EMPTY, timeout, unit);
+    }
+
+    /**
+     * Submits {@code callable} together with {@code args} to the root process and blocks the
+     * calling thread for at most {@code timeout} {@code unit}s.
+     *
+     * @param callable The closure to execute in the root process.
+     * @param args     Custom arguments available in the root process via
+     *                 {@link RootOptions#getArgs()}.
+     * @param timeout  Maximum time to wait.
+     * @param unit     Time unit for {@code timeout}.
+     * @param <T>      Return type of the callable.
+     * @return The value returned by the callable.
+     * @throws IOException          If IPC serialisation, transport, or the remote call fails.
+     * @throws InterruptedException If the calling thread is interrupted while waiting.
+     * @throws TimeoutException     If the operation does not complete within the timeout.
+     */
+    @Nullable
+    public static <T> T executeBlocking(
+            @NonNull RootCallable<T> callable,
+            @NonNull RootArgs args,
+            long timeout,
+            @NonNull TimeUnit unit
     ) throws IOException, InterruptedException, TimeoutException {
         try {
-            return submit(callable).get(timeout, unit);
+            return submit(callable, args).get(timeout, unit);
         } catch (ExecutionException e) {
             Throwable cause = e.getCause();
             if (cause instanceof IOException) throw (IOException) cause;
@@ -219,9 +281,21 @@ public static <T> T executeBlocking(
      *
      * @throws IOException On any serialization, IPC, or type-mismatch error.
      */
-    @SuppressWarnings("unchecked")
     @Nullable
     static <T> T executeSync(@NonNull RootCallable<T> callable) throws IOException {
+        return executeSync(callable, RootArgs.EMPTY);
+    }
+
+    /**
+     * Core synchronous IPC routine with custom arguments.  Wraps {@code callable} and
+     * {@code args} in a {@link CallableEnvelope}, serializes the envelope into a pipe,
+     * hands the read-end to the root service, then reads and deserializes the result.
+     *
+     * @throws IOException On any serialization, IPC, or type-mismatch error.
+     */
+    @SuppressWarnings("unchecked")
+    @Nullable
+    static <T> T executeSync(@NonNull RootCallable<T> callable, @NonNull RootArgs args) throws IOException {
         IRootThread svc;
         try {
             svc = sRootServiceFuture.get();
@@ -245,7 +319,7 @@ static <T> T executeSync(@NonNull RootCallable<T> callable) throws IOException {
                          new ParcelFileDescriptor.AutoCloseOutputStream(callableWrite);
                  Output output = new Output(fos)) {
                 KryoManager kryo = buildKryo(null);
-                kryo.writeClassAndObject(output, callable);
+                kryo.writeClassAndObject(output, new CallableEnvelope(callable, args));
                 output.flush();
             }
 
@@ -387,7 +461,23 @@ public Parcelable read(Kryo kryo, Input input, Class<? extends Parcelable> type)
     }
 
     public static final Companion Companion = new Companion();
+
     public static final class Companion {
-        private Companion() {}
+        private Companion() {
+        }
+    }
+
+    /**
+     * Serialization envelope that bundles a {@link RootCallable} with its {@link RootArgs}
+     * so both travel through the same Kryo-serialized pipe in a single pass.
+     */
+    record CallableEnvelope(RootCallable<?> callable, RootArgs args) implements Serializable {
+        @Serial
+        private static final long serialVersionUID = 1L;
+
+        CallableEnvelope(@NonNull RootCallable<?> callable, @NonNull RootArgs args) {
+            this.callable = callable;
+            this.args = args;
+        }
     }
 }
diff --git a/thread/src/main/java/dev/mmrlx/thread/RootThreadService.java b/thread/src/main/java/dev/mmrlx/thread/RootThreadService.java
@@ -91,18 +91,19 @@ public void execute(
                     RootThread.KryoManager kryo = RootThread.buildKryo(
                             getAppClassResolver(),
                             RootThreadBinder.class.getClassLoader());
-                    RootCallable<?> callable = (RootCallable<?>) kryo.readClassAndObject(input);
+                    RootThread.CallableEnvelope envelope =
+                            (RootThread.CallableEnvelope) kryo.readClassAndObject(input);
 
                     try {
-                        RootOptions options = new RootOptions(mContext);
-                        result = callable.call(options);
+                        RootOptions options = new RootOptions(mContext, envelope.args());
+                        result = envelope.callable().call(options);
                     } catch (Throwable t) {
                         Log.e(TAG, "Root callable threw", t);
                         result = t;
                     }
 
                 } catch (Exception e) {
-                    Log.e(TAG, "Failed to deserialise callable", e);
+                    Log.e(TAG, "Failed to deserialize callable", e);
                     result = new IOException("Deserialisation failed in root process", e);
                 }
 
diff --git a/thread/src/main/java/dev/mmrlx/thread/ktx/RootThread.kt b/thread/src/main/java/dev/mmrlx/thread/ktx/RootThread.kt
