HierarchicalStateMachine源代码

1. /** 2. * Copyright (C) 2009 The Android Open Source Project 3. * 4. * Licensed under the Apache License, Version 2.0 (the "License"); 5. * you may not use this file except in compliance with the License. 6. * You may obtain a copy of the License at 7. * 8. * http://www.apache.org/licenses/LICENSE-2.0 9. * 10. * Unless required by applicable law or agreed to in writing, software 11. * distributed under the License is distributed on an "AS IS" BASIS, 12. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13. * See the License for the specific language governing permissions and 14. * limitations under the License. 15. */ 16. 17. package com.android.internal.util; 18. 19. import android.os.Handler; 20. import android.os.HandlerThread; 21. import android.os.Looper; 22. import android.os.Message; 23. import android.util.Log; 24. 25. import java.util.ArrayList; 26. import java.util.HashMap; 27. 28. /** 29. * {@hide} 30. * 31. * A hierarchical state machine is a state machine which processes messages 32. * and can have states arranged hierarchically. A state is a <code>HierarchicalState</code> 33. * object and must implement <code>processMessage</code> and optionally <code>enter/exit/getName</code>. 34. * The enter/exit methods are equivalent to the construction and destruction 35. * in Object Oriented programming and are used to perform initialization and 36. * cleanup of the state respectively. The <code>getName</code> method returns the 37. * name of the state the default implementation returns the class name it may be 38. * desirable to have this return the name of the state instance name instead. 39. * In particular if a particular state class has multiple instances. 40. * 41. * When a state machine is created <code>addState</code> is used to build the 42. * hierarchy and <code>setInitialState</code> is used to identify which of these 43. * is the initial state. After construction the programmer calls <code>start</code> 44. * which initializes the state machine and calls <code>enter</code> for all of the initial 45. * state's hierarchy, starting at its eldest parent. For example given the simple 46. * state machine below after start is called mP1.enter will have been called and 47. * then mS1.enter. 48. <code> 49. mP1 50. / / 51. mS2 mS1 ----> initial state 52. </code> 53. * After the state machine is created and started, messages are sent to a state 54. * machine using <code>sendMessage</code and the messages are created using 55. * <code>obtainMessage</code>. When the state machine receives a message the 56. * current state's <code>processMessage</code> is invoked. In the above example 57. * mS1.processMessage will be invoked first. The state may use <code>transitionTo</code> 58. * to change the current state to a new state 59. * 60. * Each state in the state machine may have a zero or one parent states and if 61. * a child state is unable to handle a message it may have the message processed 62. * by its parent by returning false. If a message is never processed <code>unhandledMessage</code> 63. * will be invoked to give one last chance for the state machine to process 64. * the message. 65. * 66. * When all processing is completed a state machine may choose to call 67. * <code>transitionToHaltingState</code>. When the current <code>processingMessage</code> 68. * returns the state machine will transfer to an internal <code>HaltingState</code> 69. * and invoke <code>halting</code>. Any message subsequently received by the state 70. * machine will cause <code>haltedProcessMessage</code> to be invoked. 71. * 72. * If it is desirable to completely stop the state machine call <code>quit</code>. This 73. * will exit the current state and its parent and then exit from the controlling thread 74. * and no further messages will be processed. 75. * 76. * In addition to <code>processMessage</code> each <code>HierarchicalState</code> has 77. * an <code>enter</code> method and <code>exit</exit> method which may be overridden. 78. * 79. * Since the states are arranged in a hierarchy transitioning to a new state 80. * causes current states to be exited and new states to be entered. To determine 81. * the list of states to be entered/exited the common parent closest to 82. * the current state is found. We then exit from the current state and its 83. * parent's up to but not including the common parent state and then enter all 84. * of the new states below the common parent down to the destination state. 85. * If there is no common parent all states are exited and then the new states 86. * are entered. 87. * 88. * Two other methods that states can use are <code>deferMessage</code> and 89. * <code>sendMessageAtFrontOfQueue</code>. The <code>sendMessageAtFrontOfQueue</code> sends 90. * a message but places it on the front of the queue rather than the back. The 91. * <code>deferMessage</code> causes the message to be saved on a list until a 92. * transition is made to a new state. At which time all of the deferred messages 93. * will be put on the front of the state machine queue with the oldest message 94. * at the front. These will then be processed by the new current state before 95. * any other messages that are on the queue or might be added later. Both of 96. * these are protected and may only be invoked from within a state machine. 97. * 98. * To illustrate some of these properties we'll use state machine with 8 99. * state hierarchy: 100. <code> 101. mP0 102. / / 103. mP1 mS0 104. / / 105. mS2 mS1 106. / / / 107. mS3 mS4 mS5 ---> initial state 108. </code> 109. * 110. * After starting mS5 the list of active states is mP0, mP1, mS1 and mS5. 111. * So the order of calling processMessage when a message is received is mS5, 112. * mS1, mP1, mP0 assuming each processMessage indicates it can't handle this 113. * message by returning false. 114. * 115. * Now assume mS5.processMessage receives a message it can handle, and during 116. * the handling determines the machine should changes states. It would call 117. * transitionTo(mS4) and return true. Immediately after returning from 118. * processMessage the state machine runtime will find the common parent, 119. * which is mP1. It will then call mS5.exit, mS1.exit, mS2.enter and then 120. * mS4.enter. The new list of active states is mP0, mP1, mS2 and mS4. So 121. * when the next message is received mS4.processMessage will be invoked. 122. * 123. * To assist in describing an HSM a simple grammar has been created which 124. * is informally defined here and a formal EBNF description is at the end 125. * of the class comment. 126. * 127. * An HSM starts with the name and includes a set of hierarchical states. 128. * A state is preceeded by one or more plus signs (+), to indicate its 129. * depth and a hash (#) if its the initial state. Child states follow their 130. * parents and have one more plus sign then their parent. Inside a state 131. * are a series of messages, the actions they perform and if the processing 132. * is complete ends with a period (.). If processing isn't complete and 133. * the parent should process the message it ends with a caret (^). The 134. * actions include send a message ($MESSAGE), defer a message (%MESSAGE), 135. * transition to a new state (>MESSAGE) and an if statement 136. * (if ( expression ) { list of actions }.) 137. * 138. * The Hsm HelloWorld could documented as: 139. * 140. * HelloWorld { 141. * + # mState1. 142. * } 143. * 144. * and interpreted as HSM HelloWorld: 145. * 146. * mState1 a root state (single +) and initial state (#) which 147. * processes all messages completely, the period (.). 148. * 149. * The implementation is: 150. <code> 151. class HelloWorld extends HierarchicalStateMachine { 152. Hsm1(String name) { 153. super(name); 154. addState(mState1); 155. setInitialState(mState1); 156. } 157. 158. public static HelloWorld makeHelloWorld() { 159. HelloWorld hw = new HelloWorld("hw"); 160. hw.start(); 161. return hw; 162. } 163. 164. class State1 extends HierarchicalState { 165. @Override public boolean processMessage(Message message) { 166. Log.d(TAG, "Hello World"); 167. return true; 168. } 169. } 170. State1 mState1 = new State1(); 171. } 172. 173. void testHelloWorld() { 174. HelloWorld hw = makeHelloWorld(); 175. hw.sendMessage(hw.obtainMessage()); 176. } 177. </code> 178. * 179. * A more interesting state machine is one of four states 180. * with two independent parent states. 181. <code> 182. mP1 mP2 183. / / 184. mS2 mS1 185. </code> 186. * 187. * documented as: 188. * 189. * Hsm1 { 190. * + mP1 { 191. * CMD_2 { 192. * $CMD_3 193. * %CMD_2 194. * >mS2 195. * }. 196. * } 197. * ++ # mS1 { CMD_1{ >mS1 }^ } 198. * ++ mS2 { 199. * CMD_2{$CMD_4}. 200. * CMD_3{%CMD_3 ; >mP2}. 201. * } 202. * 203. * + mP2 e($CMD_5) { 204. * CMD_3, CMD_4. 205. * CMD_5{>HALT}. 206. * } 207. * } 208. * 209. * and interpreted as HierarchicalStateMachine Hsm1: 210. * 211. * mP1 a root state. 212. * processes message CMD_2 which sends CMD_3, defers CMD_2, and transitions to mS2 213. * 214. * mS1 a child of mP1 is the initial state: 215. * processes message CMD_1 which transitions to itself and returns false to let mP1 handle it. 216. * 217. * mS2 a child of mP1: 218. * processes message CMD_2 which send CMD_4 219. * processes message CMD_3 which defers CMD_3 and transitions to mP2 220. * 221. * mP2 a root state. 222. * on enter it sends CMD_5 223. * processes message CMD_3 224. * processes message CMD_4 225. * processes message CMD_5 which transitions to halt state 226. * 227. * The implementation is below and also in HierarchicalStateMachineTest: 228. <code> 229. class Hsm1 extends HierarchicalStateMachine { 230. private static final String TAG = "hsm1"; 231. 232. public static final int CMD_1 = 1; 233. public static final int CMD_2 = 2; 234. public static final int CMD_3 = 3; 235. public static final int CMD_4 = 4; 236. public static final int CMD_5 = 5; 237. 238. public static Hsm1 makeHsm1() { 239. Log.d(TAG, "makeHsm1 E"); 240. Hsm1 sm = new Hsm1("hsm1"); 241. sm.start(); 242. Log.d(TAG, "makeHsm1 X"); 243. return sm; 244. } 245. 246. Hsm1(String name) { 247. super(name); 248. Log.d(TAG, "ctor E"); 249. 250. // Add states, use indentation to show hierarchy 251. addState(mP1); 252. addState(mS1, mP1); 253. addState(mS2, mP1); 254. addState(mP2); 255. 256. // Set the initial state 257. setInitialState(mS1); 258. Log.d(TAG, "ctor X"); 259. } 260. 261. class P1 extends HierarchicalState { 262. @Override public void enter() { 263. Log.d(TAG, "mP1.enter"); 264. } 265. @Override public boolean processMessage(Message message) { 266. boolean retVal; 267. Log.d(TAG, "mP1.processMessage what=" + message.what); 268. switch(message.what) { 269. case CMD_2: 270. // CMD_2 will arrive in mS2 before CMD_3 271. sendMessage(obtainMessage(CMD_3)); 272. deferMessage(message); 273. transitionTo(mS2); 274. retVal = true; 275. break; 276. default: 277. // Any message we don't understand in this state invokes unhandledMessage 278. retVal = false; 279. break; 280. } 281. return retVal; 282. } 283. @Override public void exit() { 284. Log.d(TAG, "mP1.exit"); 285. } 286. } 287. 288. class S1 extends HierarchicalState { 289. @Override public void enter() { 290. Log.d(TAG, "mS1.enter"); 291. } 292. @Override public boolean processMessage(Message message) { 293. Log.d(TAG, "S1.processMessage what=" + message.what); 294. if (message.what == CMD_1) { 295. // Transition to ourself to show that enter/exit is called 296. transitionTo(mS1); 297. return true; 298. } else { 299. // Let parent process all other messages 300. return false; 301. } 302. } 303. @Override public void exit() { 304. Log.d(TAG, "mS1.exit"); 305. } 306. } 307. 308. class S2 extends HierarchicalState { 309. @Override public void enter() { 310. Log.d(TAG, "mS2.enter"); 311. } 312. @Override public boolean processMessage(Message message) { 313. boolean retVal; 314. Log.d(TAG, "mS2.processMessage what=" + message.what); 315. switch(message.what) { 316. case(CMD_2): 317. sendMessage(obtainMessage(CMD_4)); 318. retVal = true; 319. break; 320. case(CMD_3): 321. deferMessage(message); 322. transitionTo(mP2); 323. retVal = true; 324. break; 325. default: 326. retVal = false; 327. break; 328. } 329. return retVal; 330. } 331. @Override public void exit() { 332. Log.d(TAG, "mS2.exit"); 333. } 334. } 335. 336. class P2 extends HierarchicalState { 337. @Override public void enter() { 338. Log.d(TAG, "mP2.enter"); 339. sendMessage(obtainMessage(CMD_5)); 340. } 341. @Override public boolean processMessage(Message message) { 342. Log.d(TAG, "P2.processMessage what=" + message.what); 343. switch(message.what) { 344. case(CMD_3): 345. break; 346. case(CMD_4): 347. break; 348. case(CMD_5): 349. transitionToHaltingState(); 350. break; 351. } 352. return true; 353. } 354. @Override public void exit() { 355. Log.d(TAG, "mP2.exit"); 356. } 357. } 358. 359. @Override 360. protected void halting() { 361. Log.d(TAG, "halting"); 362. synchronized (this) { 363. this.notifyAll(); 364. } 365. } 366. 367. P1 mP1 = new P1(); 368. S1 mS1 = new S1(); 369. S2 mS2 = new S2(); 370. P2 mP2 = new P2(); 371. } 372. </code> 373. * 374. * If this is executed by sending two messages CMD_1 and CMD_2 375. * (Note the synchronize is only needed because we use hsm.wait()) 376. * 377. * Hsm1 hsm = makeHsm1(); 378. * synchronize(hsm) { 379. * hsm.sendMessage(obtainMessage(hsm.CMD_1)); 380. * hsm.sendMessage(obtainMessage(hsm.CMD_2)); 381. * try { 382. * // wait for the messages to be handled 383. * hsm.wait(); 384. * } catch (InterruptedException e) { 385. * Log.e(TAG, "exception while waiting " + e.getMessage()); 386. * } 387. * } 388. * 389. * 390. * The output is: 391. * 392. * D/hsm1 ( 1999): makeHsm1 E 393. * D/hsm1 ( 1999): ctor E 394. * D/hsm1 ( 1999): ctor X 395. * D/hsm1 ( 1999): mP1.enter 396. * D/hsm1 ( 1999): mS1.enter 397. * D/hsm1 ( 1999): makeHsm1 X 398. * D/hsm1 ( 1999): mS1.processMessage what=1 399. * D/hsm1 ( 1999): mS1.exit 400. * D/hsm1 ( 1999): mS1.enter 401. * D/hsm1 ( 1999): mS1.processMessage what=2 402. * D/hsm1 ( 1999): mP1.processMessage what=2 403. * D/hsm1 ( 1999): mS1.exit 404. * D/hsm1 ( 1999): mS2.enter 405. * D/hsm1 ( 1999): mS2.processMessage what=2 406. * D/hsm1 ( 1999): mS2.processMessage what=3 407. * D/hsm1 ( 1999): mS2.exit 408. * D/hsm1 ( 1999): mP1.exit 409. * D/hsm1 ( 1999): mP2.enter 410. * D/hsm1 ( 1999): mP2.processMessage what=3 411. * D/hsm1 ( 1999): mP2.processMessage what=4 412. * D/hsm1 ( 1999): mP2.processMessage what=5 413. * D/hsm1 ( 1999): mP2.exit 414. * D/hsm1 ( 1999): halting 415. * 416. * Here is the HSM a BNF grammar, this is a first stab at creating an 417. * HSM description language, suggestions corrections or alternatives 418. * would be much appreciated. 419. * 420. * Legend: 421. * {} ::= zero or more 422. * {}+ ::= one or more 423. * [] ::= zero or one 424. * () ::= define a group with "or" semantics. 425. * 426. * HSM EBNF: 427. * HSM = HSM_NAME "{" { STATE }+ "}" ; 428. * HSM_NAME = alpha_numeric_name ; 429. * STATE = INTRODUCE_STATE [ ENTER | [ ENTER EXIT ] "{" [ MESSAGES ] "}" [ EXIT ] ; 430. * INTRODUCE_STATE = { STATE_DEPTH }+ [ INITIAL_STATE_INDICATOR ] STATE_NAME ; 431. * STATE_DEPTH = "+" ; 432. * INITIAL_STATE_INDICATOR = "#" 433. * ENTER = "e(" SEND_ACTION | TRANSITION_ACTION | HALT_ACTION ")" ; 434. * MESSAGES = { MSG_LIST MESSAGE_ACTIONS } ; 435. * MSG_LIST = { MSG_NAME { "," MSG_NAME } }; 436. * EXIT = "x(" SEND_ACTION | TRANSITION_ACTION | HALT_ACTION ")" ; 437. * PROCESS_COMPLETION = PROCESS_IN_PARENT_OR_COMPLETE | PROCESS_COMPLETE ; 438. * SEND_ACTION = "$" MSG_NAME ; 439. * DEFER_ACTION = "%" MSG_NAME ; 440. * TRANSITION_ACTION = ">" STATE_NAME ; 441. * HALT_ACTION = ">" HALT ; 442. * MESSAGE_ACTIONS = { "{" ACTION_LIST "}" } [ PROCESS_COMPLETION ] ; 443. * ACTION_LIST = ACTION { (";" | "/n") ACTION } ; 444. * ACTION = IF_ACTION | SEND_ACTION | DEFER_ACTION | TRANSITION_ACTION | HALT_ACTION ; 445. * IF_ACTION = "if(" boolean_expression ")" "{" ACTION_LIST "}" 446. * PROCESS_IN_PARENT_OR_COMPLETE = "^" ; 447. * PROCESS_COMPLETE = "." ; 448. * STATE_NAME = alpha_numeric_name ; 449. * MSG_NAME = alpha_numeric_name | ALL_OTHER_MESSAGES ; 450. * ALL_OTHER_MESSAGES = "*" ; 451. * EXP = boolean_expression ; 452. * 453. * Idioms: 454. * * { %* }. ::= All other messages will be deferred. 455. */ 456. public class HierarchicalStateMachine { 457. 458. private static final String TAG = "HierarchicalStateMachine"; 459. private String mName; 460. 461. public static final int HSM_QUIT_CMD = -1; 462. 463. private static class HsmHandler extends Handler { 464. 465. /** The debug flag */ 466. private boolean mDbg = false; 467. 468. /** The quit object */ 469. private static final Object mQuitObj = new Object(); 470. 471. /** A list of messages that this state machine has processed */ 472. private ProcessedMessages mProcessedMessages = new ProcessedMessages(); 473. 474. /** true if construction of the state machine has not been completed */ 475. private boolean mIsConstructionCompleted; 476. 477. /** Stack used to manage the current hierarchy of states */ 478. private StateInfo mStateStack[]; 479. 480. /** Top of mStateStack */ 481. private int mStateStackTopIndex = -1; 482. 483. /** A temporary stack used to manage the state stack */ 484. private StateInfo mTempStateStack[]; 485. 486. /** The top of the mTempStateStack */ 487. private int mTempStateStackCount; 488. 489. /** State used when state machine is halted */ 490. private HaltingState mHaltingState = new HaltingState(); 491. 492. /** State used when state machine is quitting */ 493. private QuittingState mQuittingState = new QuittingState(); 494. 495. /** Reference to the HierarchicalStateMachine */ 496. private HierarchicalStateMachine mHsm; 497. 498. /** 499. * Information about a state. 500. * Used to maintain the hierarchy. 501. */ 502. private class StateInfo { 503. /** The state */ 504. HierarchicalState state; 505. 506. /** The parent of this state, null if there is no parent */ 507. StateInfo parentStateInfo; 508. 509. /** True when the state has been entered and on the stack */ 510. boolean active; 511. 512. /** 513. * Convert StateInfo to string 514. */ 515. @Override 516. public String toString() { 517. return "state=" + state.getName() + ",active=" + active 518. + ",parent=" + ((parentStateInfo == null) ? 519. "null" : parentStateInfo.state.getName()); 520. } 521. } 522. 523. /** The map of all of the states in the state machine */ 524. private HashMap<HierarchicalState, StateInfo> mStateInfo = 525. new HashMap<HierarchicalState, StateInfo>(); 526. 527. /** The initial state that will process the first message */ 528. private HierarchicalState mInitialState; 529. 530. /** The destination state when transitionTo has been invoked */ 531. private HierarchicalState mDestState; 532. 533. /** The list of deferred messages */ 534. private ArrayList<Message> mDeferredMessages = new ArrayList<Message>(); 535. 536. /** 537. * State entered when transitionToHaltingState is called. 538. */ 539. private class HaltingState extends HierarchicalState { 540. @Override 541. public boolean processMessage(Message msg) { 542. mHsm.haltedProcessMessage(msg); 543. return true; 544. } 545. } 546. 547. /** 548. * State entered when a valid quit message is handled. 549. */ 550. private class QuittingState extends HierarchicalState { 551. @Override 552. public boolean processMessage(Message msg) { 553. // Ignore 554. return false; 555. } 556. } 557. 558. /** 559. * Handle messages sent to the state machine by calling 560. * the current state's processMessage. It also handles 561. * the enter/exit calls and placing any deferred messages 562. * back onto the queue when transitioning to a new state. 563. */ 564. @Override 565. public final void handleMessage(Message msg) { 566. if (mDbg) Log.d(TAG, "handleMessage: E msg.what=" + msg.what); 567. 568. /** 569. * Check that construction was completed 570. */ 571. if (!mIsConstructionCompleted) { 572. Log.e(TAG, "The start method not called, ignore msg: " + msg); 573. return; 574. } 575. 576. /** 577. * Process the message abiding by the hierarchical semantics 578. * and perform any requested transitions. 579. */ 580. processMsg(msg); 581. performTransitions(); 582. 583. if (mDbg) Log.d(TAG, "handleMessage: X"); 584. } 585. 586. /** 587. * Do any transitions 588. */ 589. private void performTransitions() { 590. /** 591. * If transitionTo has been called, exit and then enter 592. * the appropriate states. We loop on this to allow 593. * enter and exit methods to use transitionTo. 594. */ 595. HierarchicalState destState = null; 596. while (mDestState != null) { 597. if (mDbg) Log.d(TAG, "handleMessage: new destination call exit"); 598. 599. /** 600. * Save mDestState locally and set to null 601. * to know if enter/exit use transitionTo. 602. */ 603. destState = mDestState; 604. mDestState = null; 605. 606. /** 607. * Determine the states to exit and enter and return the 608. * common ancestor state of the enter/exit states. Then 609. * invoke the exit methods then the enter methods. 610. */ 611. StateInfo commonStateInfo = setupTempStateStackWithStatesToEnter(destState); 612. invokeExitMethods(commonStateInfo); 613. int stateStackEnteringIndex = moveTempStateStackToStateStack(); 614. invokeEnterMethods(stateStackEnteringIndex); 615. 616. 617. /** 618. * Since we have transitioned to a new state we need to have 619. * any deferred messages moved to the front of the message queue 620. * so they will be processed before any other messages in the 621. * message queue. 622. */ 623. moveDeferredMessageAtFrontOfQueue(); 624. } 625. 626. /** 627. * After processing all transitions check and 628. * see if the last transition was to quit or halt. 629. */ 630. if (destState != null) { 631. if (destState == mQuittingState) { 632. /** 633. * We are quitting so ignore all messages. 634. */ 635. mHsm.quitting(); 636. if (mHsm.mHsmThread != null) { 637. // If we made the thread then quit looper 638. getLooper().quit(); 639. } 640. } else if (destState == mHaltingState) { 641. /** 642. * Call halting() if we've transitioned to the halting 643. * state. All subsequent messages will be processed in 644. * in the halting state which invokes haltedProcessMessage(msg); 645. */ 646. mHsm.halting(); 647. } 648. } 649. } 650. 651. /** 652. * Complete the construction of the state machine. 653. */ 654. private final void completeConstruction() { 655. if (mDbg) Log.d(TAG, "completeConstruction: E"); 656. 657. /** 658. * Determine the maximum depth of the state hierarchy 659. * so we can allocate the state stacks. 660. */ 661. int maxDepth = 0; 662. for (StateInfo si : mStateInfo.values()) { 663. int depth = 0; 664. for (StateInfo i = si; i != null; depth++) { 665. i = i.parentStateInfo; 666. } 667. if (maxDepth < depth) { 668. maxDepth = depth; 669. } 670. } 671. if (mDbg) Log.d(TAG, "completeConstruction: maxDepth=" + maxDepth); 672. 673. mStateStack = new StateInfo[maxDepth]; 674. mTempStateStack = new StateInfo[maxDepth]; 675. setupInitialStateStack(); 676. 677. /** 678. * Construction is complete call all enter methods 679. * starting at the first entry. 680. */ 681. mIsConstructionCompleted = true; 682. invokeEnterMethods(0); 683. 684. /** 685. * Perform any transitions requested by the enter methods 686. */ 687. performTransitions(); 688. 689. if (mDbg) Log.d(TAG, "completeConstruction: X"); 690. } 691. 692. /** 693. * Process the message. If the current state doesn't handle 694. * it, call the states parent and so on. If it is never handled then 695. * call the state machines unhandledMessage method. 696. */ 697. private final void processMsg(Message msg) { 698. StateInfo curStateInfo = mStateStack[mStateStackTopIndex]; 699. if (mDbg) { 700. Log.d(TAG, "processMsg: " + curStateInfo.state.getName()); 701. } 702. while (!curStateInfo.state.processMessage(msg)) { 703. /** 704. * Not processed 705. */ 706. curStateInfo = curStateInfo.parentStateInfo; 707. if (curStateInfo == null) { 708. /** 709. * No parents left so it's not handled 710. */ 711. mHsm.unhandledMessage(msg); 712. if (isQuit(msg)) { 713. transitionTo(mQuittingState); 714. } 715. break; 716. } 717. if (mDbg) { 718. Log.d(TAG, "processMsg: " + curStateInfo.state.getName()); 719. } 720. } 721. 722. /** 723. * Record that we processed the message 724. */ 725. if (curStateInfo != null) { 726. HierarchicalState orgState = mStateStack[mStateStackTopIndex].state; 727. mProcessedMessages.add(msg, curStateInfo.state, orgState); 728. } else { 729. mProcessedMessages.add(msg, null, null); 730. } 731. } 732. 733. /** 734. * Call the exit method for each state from the top of stack 735. * up to the common ancestor state. 736. */ 737. private final void invokeExitMethods(StateInfo commonStateInfo) { 738. while ((mStateStackTopIndex >= 0) && 739. (mStateStack[mStateStackTopIndex] != commonStateInfo)) { 740. HierarchicalState curState = mStateStack[mStateStackTopIndex].state; 741. if (mDbg) Log.d(TAG, "invokeExitMethods: " + curState.getName()); 742. curState.exit(); 743. mStateStack[mStateStackTopIndex].active = false; 744. mStateStackTopIndex -= 1; 745. } 746. } 747. 748. /** 749. * Invoke the enter method starting at the entering index to top of state stack 750. */ 751. private final void invokeEnterMethods(int stateStackEnteringIndex) { 752. for (int i = stateStackEnteringIndex; i <= mStateStackTopIndex; i++) { 753. if (mDbg) Log.d(TAG, "invokeEnterMethods: " + mStateStack[i].state.getName()); 754. mStateStack[i].state.enter(); 755. mStateStack[i].active = true; 756. } 757. } 758. 759. /** 760. * Move the deferred message to the front of the message queue. 761. */ 762. private final void moveDeferredMessageAtFrontOfQueue() { 763. /** 764. * The oldest messages on the deferred list must be at 765. * the front of the queue so start at the back, which 766. * as the most resent message and end with the oldest 767. * messages at the front of the queue. 768. */ 769. for (int i = mDeferredMessages.size() - 1; i >= 0; i-- ) { 770. Message curMsg = mDeferredMessages.get(i); 771. if (mDbg) Log.d(TAG, "moveDeferredMessageAtFrontOfQueue; what=" + curMsg.what); 772. sendMessageAtFrontOfQueue(curMsg); 773. } 774. mDeferredMessages.clear(); 775. } 776. 777. /** 778. * Move the contents of the temporary stack to the state stack 779. * reversing the order of the items on the temporary stack as 780. * they are moved. 781. * 782. * @return index into mStateState where entering needs to start 783. */ 784. private final int moveTempStateStackToStateStack() { 785. int startingIndex = mStateStackTopIndex + 1; 786. int i = mTempStateStackCount - 1; 787. int j = startingIndex; 788. while (i >= 0) { 789. if (mDbg) Log.d(TAG, "moveTempStackToStateStack: i=" + i + ",j=" + j); 790. mStateStack[j] = mTempStateStack[i]; 791. j += 1; 792. i -= 1; 793. } 794. 795. mStateStackTopIndex = j - 1; 796. if (mDbg) { 797. Log.d(TAG, "moveTempStackToStateStack: X mStateStackTop=" 798. + mStateStackTopIndex + ",startingIndex=" + startingIndex 799. + ",Top=" + mStateStack[mStateStackTopIndex].state.getName()); 800. } 801. return startingIndex; 802. } 803. 804. /** 805. * Setup the mTempStateStack with the states we are going to enter. 806. * 807. * This is found by searching up the destState's ancestors for a 808. * state that is already active i.e. StateInfo.active == true. 809. * The destStae and all of its inactive parents will be on the 810. * TempStateStack as the list of states to enter. 811. * 812. * @return StateInfo of the common ancestor for the destState and 813. * current state or null if there is no common parent. 814. */ 815. private final StateInfo setupTempStateStackWithStatesToEnter(HierarchicalState destState) { 816. /** 817. * Search up the parent list of the destination state for an active 818. * state. Use a do while() loop as the destState must always be entered 819. * even if it is active. This can happen if we are exiting/entering 820. * the current state. 821. */ 822. mTempStateStackCount = 0; 823. StateInfo curStateInfo = mStateInfo.get(destState); 824. do { 825. mTempStateStack[mTempStateStackCount++] = curStateInfo; 826. curStateInfo = curStateInfo.parentStateInfo; 827. } while ((curStateInfo != null) && !curStateInfo.active); 828. 829. if (mDbg) { 830. Log.d(TAG, "setupTempStateStackWithStatesToEnter: X mTempStateStackCount=" 831. + mTempStateStackCount + ",curStateInfo: " + curStateInfo); 832. } 833. return curStateInfo; 834. } 835. 836. /** 837. * Initialize StateStack to mInitialState. 838. */ 839. private final void setupInitialStateStack() { 840. if (mDbg) { 841. Log.d(TAG, "setupInitialStateStack: E mInitialState=" 842. + mInitialState.getName()); 843. } 844. 845. StateInfo curStateInfo = mStateInfo.get(mInitialState); 846. for (mTempStateStackCount = 0; curStateInfo != null; mTempStateStackCount++) { 847. mTempStateStack[mTempStateStackCount] = curStateInfo; 848. curStateInfo = curStateInfo.parentStateInfo; 849. } 850. 851. // Empty the StateStack 852. mStateStackTopIndex = -1; 853. 854. moveTempStateStackToStateStack(); 855. } 856. 857. /** 858. * @return current state 859. */ 860. private final HierarchicalState getCurrentState() { 861. return mStateStack[mStateStackTopIndex].state; 862. } 863. 864. /** 865. * Add a new state to the state machine. Bottom up addition 866. * of states is allowed but the same state may only exist 867. * in one hierarchy. 868. * 869. * @param state the state to add 870. * @param parent the parent of state 871. * @return stateInfo for this state 872. */ 873. private final StateInfo addState(HierarchicalState state, HierarchicalState parent) { 874. if (mDbg) { 875. Log.d(TAG, "addStateInternal: E state=" + state.getName() 876. + ",parent=" + ((parent == null) ? "" : parent.getName())); 877. } 878. StateInfo parentStateInfo = null; 879. if (parent != null) { 880. parentStateInfo = mStateInfo.get(parent); 881. if (parentStateInfo == null) { 882. // Recursively add our parent as it's not been added yet. 883. parentStateInfo = addState(parent, null); 884. } 885. } 886. StateInfo stateInfo = mStateInfo.get(state); 887. if (stateInfo == null) { 888. stateInfo = new StateInfo(); 889. mStateInfo.put(state, stateInfo); 890. } 891. 892. // Validate that we aren't adding the same state in two different hierarchies. 893. if ((stateInfo.parentStateInfo != null) && 894. (stateInfo.parentStateInfo != parentStateInfo)) { 895. throw new RuntimeException("state already added"); 896. } 897. stateInfo.state = state; 898. stateInfo.parentStateInfo = parentStateInfo; 899. stateInfo.active = false; 900. if (mDbg) Log.d(TAG, "addStateInternal: X stateInfo: " + stateInfo); 901. return stateInfo; 902. } 903. 904. /** 905. * Constructor 906. * 907. * @param looper for dispatching messages 908. * @param hsm the hierarchical state machine 909. */ 910. private HsmHandler(Looper looper, HierarchicalStateMachine hsm) { 911. super(looper); 912. mHsm = hsm; 913. 914. addState(mHaltingState, null); 915. addState(mQuittingState, null); 916. } 917. 918. /** @see HierarchicalStateMachine#setInitialState(HierarchicalState) */ 919. private final void setInitialState(HierarchicalState initialState) { 920. if (mDbg) Log.d(TAG, "setInitialState: initialState" + initialState.getName()); 921. mInitialState = initialState; 922. } 923. 924. /** @see HierarchicalStateMachine#transitionTo(HierarchicalState) */ 925. private final void transitionTo(HierarchicalState destState) { 926. if (mDbg) Log.d(TAG, "StateMachine.transitionTo EX destState" + destState.getName()); 927. mDestState = destState; 928. } 929. 930. /** @see HierarchicalStateMachine#deferMessage(Message) */ 931. private final void deferMessage(Message msg) { 932. if (mDbg) Log.d(TAG, "deferMessage: msg=" + msg.what); 933. 934. /* Copy the "msg" to "newMsg" as "msg" will be recycled */ 935. Message newMsg = obtainMessage(); 936. newMsg.copyFrom(msg); 937. 938. mDeferredMessages.add(newMsg); 939. } 940. 941. /** @see HierarchicalStateMachine#deferMessage(Message) */ 942. private final void quit() { 943. if (mDbg) Log.d(TAG, "quit:"); 944. sendMessage(obtainMessage(HSM_QUIT_CMD, mQuitObj)); 945. } 946. 947. /** @see HierarchicalStateMachine#isQuit(Message) */ 948. private final boolean isQuit(Message msg) { 949. return (msg.what == HSM_QUIT_CMD) && (msg.obj == mQuitObj); 950. } 951. 952. /** @see HierarchicalStateMachine#isDbg() */ 953. private final boolean isDbg() { 954. return mDbg; 955. } 956. 957. /** @see HierarchicalStateMachine#setDbg(boolean) */ 958. private final void setDbg(boolean dbg) { 959. mDbg = dbg; 960. } 961. 962. /** @see HierarchicalStateMachine#setProcessedMessagesSize(int) */ 963. private final void setProcessedMessagesSize(int maxSize) { 964. mProcessedMessages.setSize(maxSize); 965. } 966. 967. /** @see HierarchicalStateMachine#getProcessedMessagesSize() */ 968. private final int getProcessedMessagesSize() { 969. return mProcessedMessages.size(); 970. } 971. 972. /** @see HierarchicalStateMachine#getProcessedMessagesCount() */ 973. private final int getProcessedMessagesCount() { 974. return mProcessedMessages.count(); 975. } 976. 977. /** @see HierarchicalStateMachine#getProcessedMessage(int) */ 978. private final ProcessedMessages.Info getProcessedMessage(int index) { 979. return mProcessedMessages.get(index); 980. } 981. 982. } 983. 984. private HsmHandler mHsmHandler; 985. private HandlerThread mHsmThread; 986. 987. /** 988. * Initialize. 989. * 990. * @param looper for this state machine 991. * @param name of the state machine 992. */ 993. private void initStateMachine(String name, Looper looper) { 994. mName = name; 995. mHsmHandler = new HsmHandler(looper, this); 996. } 997. 998. /** 999. * Constructor creates an HSM with its own thread.1000. *1001. * @param name of the state machine1002. */1003. protected HierarchicalStateMachine(String name) {1004. mHsmThread = new HandlerThread(name);1005. mHsmThread.start();1006. Looper looper = mHsmThread.getLooper();1007.1008. initStateMachine(name, looper);1009. }1010.1011. /**1012. * Constructor creates an HSMStateMachine using the looper.1013. *1014. * @param name of the state machine1015. */1016. protected HierarchicalStateMachine(String name, Looper looper) {1017. initStateMachine(name, looper);1018. }1019.1020. /**1021. * Add a new state to the state machine1022. * @param state the state to add1023. * @param parent the parent of state1024. */1025. protected final void addState(HierarchicalState state, HierarchicalState parent) {1026. mHsmHandler.addState(state, parent);1027. }1028. /**1029. * @return current state1030. */1031. protected final HierarchicalState getCurrentState() {1032. return mHsmHandler.getCurrentState();1033. }1034.1035.1036. /**1037. * Add a new state to the state machine, parent will be null1038. * @param state to add1039. */1040. protected final void addState(HierarchicalState state) {1041. mHsmHandler.addState(state, null);1042. }1043.1044. /**1045. * Set the initial state. This must be invoked before1046. * and messages are sent to the state machine.1047. *1048. * @param initialState is the state which will receive the first message.1049. */1050. protected final void setInitialState(HierarchicalState initialState) {1051. mHsmHandler.setInitialState(initialState);1052. }1053.1054. /**1055. * transition to destination state. Upon returning1056. * from processMessage the current state's exit will1057. * be executed and upon the next message arriving1058. * destState.enter will be invoked.1059. *1060. * @param destState will be the state that receives the next message.1061. */1062. protected final void transitionTo(HierarchicalState destState) {1063. mHsmHandler.transitionTo(destState);1064. }1065.1066. /**1067. * transition to halt state. Upon returning1068. * from processMessage we will exit all current1069. * states, execute the halting() method and then1070. * all subsequent messages haltedProcessMesage1071. * will be called.1072. */1073. protected final void transitionToHaltingState() {1074. mHsmHandler.transitionTo(mHsmHandler.mHaltingState);1075. }1076.1077. /**1078. * Defer this message until next state transition.1079. * Upon transitioning all deferred messages will be1080. * placed on the queue and reprocessed in the original1081. * order. (i.e. The next state the oldest messages will1082. * be processed first)1083. *1084. * @param msg is deferred until the next transition.1085. */1086. protected final void deferMessage(Message msg) {1087. mHsmHandler.deferMessage(msg);1088. }1089.1090.1091. /**1092. * Called when message wasn't handled1093. *1094. * @param msg that couldn't be handled.1095. */1096. protected void unhandledMessage(Message msg) {1097. Log.e(TAG, mName + " - unhandledMessage: msg.what=" + msg.what);1098. }1099.1100. /**1101. * Called for any message that is received after1102. * transitionToHalting is called.1103. */1104. protected void haltedProcessMessage(Message msg) {1105. }1106.1107. /**1108. * Called after the message that called transitionToHalting1109. * is called and should be overridden by StateMachine's that1110. * call transitionToHalting.1111. */1112. protected void halting() {1113. }1114.1115. /**1116. * Called after the quitting message was NOT handled and1117. * just before the quit actually occurs.1118. */1119. protected void quitting() {1120. }1121.1122. /**1123. * @return the name1124. */1125. public final String getName() {1126. return mName;1127. }1128.1129. /**1130. * Set size of messages to maintain and clears all current messages.1131. *1132. * @param maxSize number of messages to maintain at anyone time.1133. */1134. public final void setProcessedMessagesSize(int maxSize) {1135. mHsmHandler.setProcessedMessagesSize(maxSize);1136. }1137.1138. /**1139. * @return number of messages processed1140. */1141. public final int getProcessedMessagesSize() {1142. return mHsmHandler.getProcessedMessagesSize();1143. }1144.1145. /**1146. * @return the total number of messages processed1147. */1148. public final int getProcessedMessagesCount() {1149. return mHsmHandler.getProcessedMessagesCount();1150. }1151.1152. /**1153. * @return a processed message1154. */1155. public final ProcessedMessages.Info getProcessedMessage(int index) {1156. return mHsmHandler.getProcessedMessage(index);1157. }1158.1159. /**1160. * @return Handler1161. */1162. public final Handler getHandler() {1163. return mHsmHandler;1164. }1165.1166. /**1167. * Get a message and set Message.target = this.1168. *1169. * @return message1170. */1171. public final Message obtainMessage()1172. {1173. return Message.obtain(mHsmHandler);1174. }1175.1176. /**1177. * Get a message and set Message.target = this and what1178. *1179. * @param what is the assigned to Message.what.1180. * @return message1181. */1182. public final Message obtainMessage(int what) {1183. return Message.obtain(mHsmHandler, what);1184. }1185.1186. /**1187. * Get a message and set Message.target = this,1188. * what and obj.1189. *1190. * @param what is the assigned to Message.what.1191. * @param obj is assigned to Message.obj.1192. * @return message1193. */1194. public final Message obtainMessage(int what, Object obj)1195. {1196. return Message.obtain(mHsmHandler, what, obj);1197. }1198.1199. /**1200. * Enqueue a message to this state machine.1201. */1202. public final void sendMessage(int what) {1203. mHsmHandler.sendMessage(obtainMessage(what));1204. }1205.1206. /**1207. * Enqueue a message to this state machine.1208. */1209. public final void sendMessage(int what, Object obj) {1210. mHsmHandler.sendMessage(obtainMessage(what,obj));1211. }1212.1213. /**1214. * Enqueue a message to this state machine.1215. */1216. public final void sendMessage(Message msg) {1217. mHsmHandler.sendMessage(msg);1218. }1219.1220. /**1221. * Enqueue a message to this state machine after a delay.1222. */1223. public final void sendMessageDelayed(int what, long delayMillis) {1224. mHsmHandler.sendMessageDelayed(obtainMessage(what), delayMillis);1225. }1226.1227. /**1228. * Enqueue a message to this state machine after a delay.1229. */1230. public final void sendMessageDelayed(int what, Object obj, long delayMillis) {1231. mHsmHandler.sendMessageDelayed(obtainMessage(what, obj), delayMillis);1232. }1233.1234. /**1235. * Enqueue a message to this state machine after a delay.1236. */1237. public final void sendMessageDelayed(Message msg, long delayMillis) {1238. mHsmHandler.sendMessageDelayed(msg, delayMillis);1239. }1240.1241. /**1242. * Enqueue a message to the front of the queue for this state machine.1243. * Protected, may only be called by instances of HierarchicalStateMachine.1244. */1245. protected final void sendMessageAtFrontOfQueue(int what, Object obj) {1246. mHsmHandler.sendMessageAtFrontOfQueue(obtainMessage(what, obj));1247. }1248.1249. /**1250. * Enqueue a message to the front of the queue for this state machine.1251. * Protected, may only be called by instances of HierarchicalStateMachine.1252. */1253. protected final void sendMessageAtFrontOfQueue(int what) {1254. mHsmHandler.sendMessageAtFrontOfQueue(obtainMessage(what));1255. }1256.1257. /**1258. * Enqueue a message to the front of the queue for this state machine.1259. * Protected, may only be called by instances of HierarchicalStateMachine.1260. */1261. protected final void sendMessageAtFrontOfQueue(Message msg) {1262. mHsmHandler.sendMessageAtFrontOfQueue(msg);1263. }1264.1265. /**1266. * Conditionally quit the looper and stop execution.1267. *1268. * This sends the HSM_QUIT_MSG to the state machine and1269. * if not handled by any state's processMessage then the1270. * state machine will be stopped and no further messages1271. * will be processed.1272. */1273. public final void quit() {1274. mHsmHandler.quit();1275. }1276.1277. /**1278. * @return ture if msg is quit1279. */1280. protected final boolean isQuit(Message msg) {1281. return mHsmHandler.isQuit(msg);1282. }1283.1284. /**1285. * @return if debugging is enabled1286. */1287. public boolean isDbg() {1288. return mHsmHandler.isDbg();1289. }1290.1291. /**1292. * Set debug enable/disabled.1293. *1294. * @param dbg is true to enable debugging.1295. */1296. public void setDbg(boolean dbg) {1297. mHsmHandler.setDbg(dbg);1298. }1299.1300. /**1301. * Start the state machine.1302. */1303. public void start() {1304. /** Send the complete construction message */1305. mHsmHandler.completeConstruction();1306. }1307. }