libbinder: 'deprecate' note on BinderService
Asked recently about this, and I've wanted to delete it for a long time
(although there are quite a few users of it). Instead, documenting best
practices and also why this should be removed, for now.
Bug: N/A
Test: N/A
Change-Id: I9476f0bda28940be8c7855b6fcec299a9efd84b1
diff --git a/libs/binder/include/binder/BinderService.h b/libs/binder/include/binder/BinderService.h
index 5776f3c..e58d489 100644
--- a/libs/binder/include/binder/BinderService.h
+++ b/libs/binder/include/binder/BinderService.h
@@ -26,6 +26,24 @@
#include <binder/ProcessState.h>
#include <binder/IServiceManager.h>
+// WARNING: deprecated - DO NOT USE - prefer to setup service directly.
+//
+// This class embellishes a class with a few static methods which can be used in
+// limited circumstances (when one service needs to be registered and
+// published). However, this is an anti-pattern:
+// - these methods are aliases of existing methods, and as such, represent an
+// incremental amount of information required to understand the system but
+// which does not actually save in terms of lines of code. For instance, users
+// of this class should be surprised to know that this will start up to 16
+// threads in the binder threadpool.
+// - the template instantiation costs need to be paid, even though everything
+// done here is generic.
+// - the getServiceName API here is undocumented and non-local (for instance,
+// this unnecessarily assumes a single service type will only be instantiated
+// once with no arguments).
+//
+// So, DO NOT USE.
+
// ---------------------------------------------------------------------------
namespace android {