io.grpc.binder.internal

Class OneWayBinderProxy

java.lang.Object

io.grpc.binder.internal.OneWayBinderProxy

public abstract class OneWayBinderProxy
extends java.lang.Object

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 Binder instance. But when the target Service is hosted in the same process, Android supplies you with that local instance of 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 IBinder.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.

Field Summary

Fields

Modifier and Type	Field and Description
protected android.os.IBinder	delegate

Method Summary

Modifier and Type	Method and Description
android.os.IBinder	getDelegate() Returns the wrapped IBinder for the purpose of calling methods other than IBinder.transact(int, Parcel, Parcel, int).
abstract void	transact(int code, io.grpc.binder.internal.ParcelHolder data) Enqueues a transaction for the wrapped IBinder with guaranteed "oneway" semantics.
protected boolean	transactAndRecycleParcel(int code, android.os.Parcel data)
static OneWayBinderProxy	wrap(android.os.IBinder iBinder, java.util.concurrent.Executor inProcessThreadHopExecutor) Returns a new instance of OneWayBinderProxy that wraps iBinder.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

delegate

protected final android.os.IBinder delegate

Method Detail

wrap

public static OneWayBinderProxy wrap(android.os.IBinder iBinder,
                                     java.util.concurrent.Executor inProcessThreadHopExecutor)

Returns a new instance of OneWayBinderProxy that wraps iBinder.

Parameters:

iBinder - the binder to wrap

inProcessThreadHopExecutor - a non-direct Executor used to dispatch calls to onTransact(), if necessary

Returns:

a new instance of OneWayBinderProxy

transact

public abstract void transact(int code,
                              io.grpc.binder.internal.ParcelHolder data)
                       throws android.os.RemoteException

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

NB: Unlike IBinder.transact(int, android.os.Parcel, android.os.Parcel, int), implementations of this method take ownership of the data Parcel. When this method returns, data will normally be empty, but callers should still unconditionally ParcelHolder.close() it to avoid a leak in case they or the 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

Throws:

android.os.RemoteException - if the transaction could not even be queued for dispatch on the server. Failures from Binder.onTransact(int, android.os.Parcel, android.os.Parcel, int) are *never* reported this way.

getDelegate

public android.os.IBinder getDelegate()

Returns the wrapped IBinder for the purpose of calling methods other than IBinder.transact(int, Parcel, Parcel, int).

transactAndRecycleParcel

protected boolean transactAndRecycleParcel(int code,
                                           android.os.Parcel data)
                                    throws android.os.RemoteException

Throws:

android.os.RemoteException