Add some documentation for cycled scanner handlers

This helps to try explaining how / when the various internal handlers
should be used. This is important to help developers understand various
threading flow orders, race conditions, and resource contention
problems. As part of the documentation this adds `MainThread` and
`WorkerThread` annotations to the deferred `Runnable` tasks' `run`
methods.

See Also:

- https://developer.android.com/studio/write/annotations.html#thread-annotations

Author: cupakromer

src/main/java/org/altbeacon/beacon/service/scanner/CycledLeScanner.java

@@ -15,6 +15,8 @@
 import android.os.HandlerThread;
 import android.os.Looper;
 import android.os.SystemClock;
+import android.support.annotation.MainThread;
+import android.support.annotation.NonNull;
 
 import org.altbeacon.beacon.BeaconManager;
 import org.altbeacon.beacon.logging.LogManager;
@@ -41,8 +43,30 @@ public abstract class CycledLeScanner {
 
     protected long mBetweenScanPeriod;
 
+    /**
+     * Main thread handle for scheduling scan cycle tasks.
+     * <p>
+     * Use this to schedule deferred tasks such as the following:
+     * <ul>
+     *     <li>{@link #scheduleScanCycleStop()}</li>
+     *     <li>{@link #scanLeDevice(Boolean) scanLeDevice(true)} from {@link #deferScanIfNeeded()}</li>
+     * </ul>
+     */
+    @NonNull
     protected final Handler mHandler = new Handler(Looper.getMainLooper());
+
+    /**
+     * Handler to background thread for interacting with the low-level Android BLE scanner.
+     * <p>
+     * Use this to queue any potentially long running BLE scanner actions such as starts and stops.
+     */
+    @NonNull
     protected final Handler mScanHandler;
+
+    /**
+     * Worker thread hosting the internal scanner message queue.
+     */
+    @NonNull
     private final HandlerThread mScanThread;
 
     protected final BluetoothCrashResolver mBluetoothCrashResolver;
@@ -177,6 +201,7 @@ public void destroy() {
         // So we stop the thread using the handler, so we make sure it happens after all other
         // waiting Runnables are finished.
         mHandler.post(new Runnable() {
+            @MainThread
             @Override
             public void run() {
                 LogManager.d(TAG, "Quitting scan thread");
@@ -270,6 +295,7 @@ protected void scheduleScanCycleStop() {
                 setWakeUpAlarm();
             }
             mHandler.postDelayed(new Runnable() {
+                @MainThread
                 @Override
                 public void run() {
                     scheduleScanCycleStop();

src/main/java/org/altbeacon/beacon/service/scanner/CycledLeScannerForJellyBeanMr2.java

@@ -5,6 +5,8 @@
 import android.bluetooth.BluetoothDevice;
 import android.content.Context;
 import android.os.SystemClock;
+import android.support.annotation.MainThread;
+import android.support.annotation.WorkerThread;
 
 import org.altbeacon.beacon.logging.LogManager;
 import org.altbeacon.bluetooth.BluetoothCrashResolver;
@@ -36,6 +38,7 @@ protected boolean deferScanIfNeeded() {
                 setWakeUpAlarm();
             }
             mHandler.postDelayed(new Runnable() {
+                @MainThread
                 @Override
                 public void run() {
                     scanLeDevice(true);
@@ -65,6 +68,7 @@ private void postStartLeScan() {
         final BluetoothAdapter.LeScanCallback leScanCallback = getLeScanCallback();
         mScanHandler.removeCallbacksAndMessages(null);
         mScanHandler.post(new Runnable() {
+            @WorkerThread
             @Override
             public void run() {
                 try {
@@ -85,6 +89,7 @@ private void postStopLeScan() {
         final BluetoothAdapter.LeScanCallback leScanCallback = getLeScanCallback();
         mScanHandler.removeCallbacksAndMessages(null);
         mScanHandler.post(new Runnable() {
+            @WorkerThread
             @Override
             public void run() {
                 try {

src/main/java/org/altbeacon/beacon/service/scanner/CycledLeScannerForLollipop.java

@@ -10,6 +10,8 @@
 import android.content.Context;
 import android.os.ParcelUuid;
 import android.os.SystemClock;
+import android.support.annotation.MainThread;
+import android.support.annotation.WorkerThread;
 
 import org.altbeacon.beacon.BeaconManager;
 import org.altbeacon.beacon.logging.LogManager;
@@ -134,6 +136,7 @@ protected boolean deferScanIfNeeded() {
                 setWakeUpAlarm();
             }
             mHandler.postDelayed(new Runnable() {
+                @MainThread
                 @Override
                 public void run() {
                     scanLeDevice(true);
@@ -190,6 +193,7 @@ private void postStartLeScan(final List<ScanFilter> filters, final ScanSettings
         final ScanCallback scanCallback = getNewLeScanCallback();
         mScanHandler.removeCallbacksAndMessages(null);
         mScanHandler.post(new Runnable() {
+            @WorkerThread
             @Override
             public void run() {
                 try {
@@ -220,6 +224,7 @@ private void postStopLeScan() {
         final ScanCallback scanCallback = getNewLeScanCallback();
         mScanHandler.removeCallbacksAndMessages(null);
         mScanHandler.post(new Runnable() {
+            @WorkerThread
             @Override
             public void run() {
                 try {