From c30f45b97f0aeefef05f51208f54eafa3499e40b Mon Sep 17 00:00:00 2001
From: Jean-Michel Trivi <jmtrivi@google.com>
Date: Wed, 26 Dec 2012 10:46:29 -0800
Subject: [PATCH] Add comments in AudioService focus and media button stack
 traversal

Add comments to reflect where and why the audio focus and media
 button stacks are traversed with an iterator, which traverses
 the stack from bottom to top.

Change-Id: I462a522195e742295d13eff5fc727e59a5d7e830
---
 media/java/android/media/AudioService.java | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/media/java/android/media/AudioService.java b/media/java/android/media/AudioService.java
index 653081da5d5ea..addb4cb2ce77f 100644
--- a/media/java/android/media/AudioService.java
+++ b/media/java/android/media/AudioService.java
@@ -4163,7 +4163,7 @@ public class AudioService extends IAudioService.Stub implements OnFinished {
      * Display in the log the current entries in the audio focus stack
      */
     private void dumpFocusStack(PrintWriter pw) {
-        pw.println("\nAudio Focus stack entries:");
+        pw.println("\nAudio Focus stack entries (last is top of stack):");
         synchronized(mAudioFocusLock) {
             Iterator<FocusStackEntry> stackIterator = mFocusStack.iterator();
             while(stackIterator.hasNext()) {
@@ -4204,6 +4204,8 @@ public class AudioService extends IAudioService.Stub implements OnFinished {
         } else {
             // focus is abandoned by a client that's not at the top of the stack,
             // no need to update focus.
+            // (using an iterator on the stack so we can safely remove an entry after having
+            //  evaluated it, traversal order doesn't matter here)
             Iterator<FocusStackEntry> stackIterator = mFocusStack.iterator();
             while(stackIterator.hasNext()) {
                 FocusStackEntry fse = (FocusStackEntry)stackIterator.next();
@@ -4226,6 +4228,8 @@ public class AudioService extends IAudioService.Stub implements OnFinished {
         // is the owner of the audio focus part of the client to remove?
         boolean isTopOfStackForClientToRemove = !mFocusStack.isEmpty() &&
                 mFocusStack.peek().mSourceRef.equals(cb);
+        // (using an iterator on the stack so we can safely remove an entry after having
+        //  evaluated it, traversal order doesn't matter here)
         Iterator<FocusStackEntry> stackIterator = mFocusStack.iterator();
         while(stackIterator.hasNext()) {
             FocusStackEntry fse = (FocusStackEntry)stackIterator.next();
@@ -4846,7 +4850,7 @@ public class AudioService extends IAudioService.Stub implements OnFinished {
      * Display in the log the current entries in the remote control focus stack
      */
     private void dumpRCStack(PrintWriter pw) {
-        pw.println("\nRemote Control stack entries:");
+        pw.println("\nRemote Control stack entries (last is top of stack):");
         synchronized(mRCStack) {
             Iterator<RemoteControlStackEntry> stackIterator = mRCStack.iterator();
             while(stackIterator.hasNext()) {
@@ -4868,7 +4872,7 @@ public class AudioService extends IAudioService.Stub implements OnFinished {
      * on RemoteControlClient data
      */
     private void dumpRCCStack(PrintWriter pw) {
-        pw.println("\nRemote Control Client stack entries:");
+        pw.println("\nRemote Control Client stack entries (last is top of stack):");
         synchronized(mRCStack) {
             Iterator<RemoteControlStackEntry> stackIterator = mRCStack.iterator();
             while(stackIterator.hasNext()) {
@@ -4910,6 +4914,8 @@ public class AudioService extends IAudioService.Stub implements OnFinished {
                 RemoteControlStackEntry oldTop = mRCStack.peek();
                 Iterator<RemoteControlStackEntry> stackIterator = mRCStack.iterator();
                 // iterate over the stack entries
+                // (using an iterator on the stack so we can safely remove an entry after having
+                //  evaluated it, traversal order doesn't matter here)
                 while(stackIterator.hasNext()) {
                     RemoteControlStackEntry rcse = (RemoteControlStackEntry)stackIterator.next();
                     if (packageName.equalsIgnoreCase(rcse.mReceiverComponent.getPackageName())) {
@@ -5039,6 +5045,8 @@ public class AudioService extends IAudioService.Stub implements OnFinished {
      * Update the remote control clients with the new "focused" client generation
      */
     private void setNewRcClientGenerationOnClients_syncRcsCurrc(int newClientGeneration) {
+        // (using an iterator on the stack so we can safely remove an entry if needed,
+        //  traversal order doesn't matter here as we update all entries)
         Iterator<RemoteControlStackEntry> stackIterator = mRCStack.iterator();
         while(stackIterator.hasNext()) {
             RemoteControlStackEntry se = stackIterator.next();