Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 658fc4fb authored by Steven Moreland's avatar Steven Moreland
Browse files

libbinder(_ndk): document getService 

This API does busy polling, and it returns after a certain number
of tries. There are a few implications related to this, which
most clients (especially in core Android) follow. However, it's
also still pretty easy to introduce errors/races when this API
is used improperly, so clearly discuss how to use it.

Fixes: 218920831
Test: N/A
Change-Id: I1a58aa4517eec8474b01fd94de7241ad3a228b1b
parent 0f899ce8

libs/binder/include/binder/IServiceManager.h

+10 −2
Original line number Diff line number Diff line
@@ -56,8 +56,16 @@ public: 
    static const int DUMP_FLAG_PROTO = 1 << 4;



    /**

     * Retrieve an existing service, blocking for a few seconds

     * if it doesn't yet exist.

     * Retrieve an existing service, blocking for a few seconds if it doesn't yet exist. This

     * does polling. A more efficient way to make sure you unblock as soon as the service is

     * available is to use waitForService or to use service notifications.

     *

     * Warning: when using this API, typically, you should call it in a loop. It's dangerous to

     * assume that nullptr could mean that the service is not available. The service could just

     * be starting. Generally, whether a service exists, this information should be declared

     * externally (for instance, an Android feature might imply the existence of a service,

     * a system property, or in the case of services in the VINTF manifest, it can be checked

     * with isDeclared).

     */

    virtual sp<IBinder>         getService( const String16& name) const = 0;

libs/binder/ndk/include_platform/android/binder_manager.h

+9 −1
Original line number Diff line number Diff line
@@ -53,11 +53,19 @@ __attribute__((warn_unused_result)) AIBinder* AServiceManager_checkService(const 
/**

 * Gets a binder object with this specific instance name. Blocks for a couple of seconds waiting on

 * it. This also implicitly calls AIBinder_incStrong (so the caller of this function is responsible

 * for calling AIBinder_decStrong).

 * for calling AIBinder_decStrong). This does polling. A more efficient way to make sure you

 * unblock as soon as the service is available is to use AIBinder_waitForService.

 *

 * WARNING: when using this API across an APEX boundary, do not use with unstable

 * AIDL services. TODO(b/139325195)

 *

 * WARNING: when using this API, typically, you should call it in a loop. It's dangerous to

 * assume that nullptr could mean that the service is not available. The service could just

 * be starting. Generally, whether a service exists, this information should be declared

 * externally (for instance, an Android feature might imply the existence of a service,

 * a system property, or in the case of services in the VINTF manifest, it can be checked

 * with AServiceManager_isDeclared).

 *

 * \param instance identifier of the service used to lookup the service.

 */

__attribute__((warn_unused_result)) AIBinder* AServiceManager_getService(const char* instance)