Package 

Class OneWayBinderProxy

  • 
public abstract class OneWayBinderProxy

    Wraps an IBinder with a safe and uniformly asynchronous transaction API.

    When the target of your bindService() call is hosted in a different process, Android supplies you with an IBinder that proxies your transactions to the remote instance. But when the target Service is hosted in the same process, Android supplies you with that local instance of android.os.Binder directly. This in-process implementation of IBinder is problematic for clients that want "oneway" transaction semantics because its transact() method simply invokes onTransact() on the caller's thread, even when the FLAG_ONEWAY flag is set. Even though this behavior is documented, its consequences with respect to reentrancy, locking, and transaction dispatch order can be surprising and dangerous.

    Wrap your IBinders with an instance of this class to ensure the following out-of-process "oneway" semantics are always in effect:

    • transact() merely enqueues the transaction for processing. It doesn't wait for onTransact() to complete.
    • transact() may fail for programming errors or transport-layer errors that are immediately obvious on the caller's side, but never for an Exception or false return value from onTransact().
    • onTransact() runs without holding any of the locks held by the thread calling transact().
    • onTransact() calls are dispatched one at a time in the same happens-before order as the corresponding calls to transact().

    NB: One difference that this class can't conceal is that calls to onTransact() are serialized per OneWayBinderProxy instance, not per instance of the wrapped IBinder. An android.os.Binder with in-process callers could still receive concurrent calls to onTransact() on different threads if callers used different OneWayBinderProxy instances or if that Binder also had out-of-process callers.

    • Method Detail

      • wrap

         static OneWayBinderProxy wrap(IBinder iBinder, Executor inProcessThreadHopExecutor)

        Returns a new instance of OneWayBinderProxy that wraps {@code iBinder}.

        Parameters:
        iBinder - the binder to wrap
        inProcessThreadHopExecutor - a non-direct Executor used to dispatch calls to onTransact(),if necessary

      • transact

         abstract void transact(int code, ParcelHolder data)

        Enqueues a transaction for the wrapped IBinder with guaranteed "oneway" semantics.

        NB: Unlike transact, implementations of this method take ownership of the {@code data} Parcel. When this method returns, {@code data} will normally be empty, but callersshould still unconditionally close it to avoid a leak in case they orthe implementation throws before ownership is transferred.

        Parameters:
        code - identifies the type of this transaction
        data - a non-empty container of the Parcel to be sent