IMPLEMENTATION NOTES
====================

========================================================================= *
MODEL BackgroundActivity AFTER QTimer + QThread
========================================================================= */

QTimer
------

PROP isSingleShot()
FUNC setSingleShot(flag)

PROP interval()
FUNC setInterval(msec)

PROP isActive()
SLOT start()
SLOT start(msec)
SIGN timeout()
SLOT stop()

QThread
-------

FUNC setTerminationEnabled()

PROP isRunning()
PROP isFinished()

SLOT start()
SIGN started()

SLOT quit()
SIGN finished()

SLOT terminate()
SIGN terminated()

BackgroundActivity implements
-----------------------------

-- timer like --

PROP isSingleShot()
FUNC setSingleShot(flag)
SIGN singleShotChanged()

PROP interval()
FUNC setInterval(msec)
SIGN intervalChanged()

PROP isStarted()
SLOT start()     -- or wait()?
SLOT start(msec)
SLOT repeat()
SLOT repeat(msec)
SLOT stop()
SIGN startedChanged()

-- thread like --

PROP isRunning()
SLOT run()
SIGN startedChanged()
SIGN startedStarted()


========================================================================= *
EXPECTED STATE TRANSITIONS
========================================================================= *

  ____________________________
 [____________IDLE____________]

       | ^             | ^
       | |             | |
  start| |stop      run| |
       | |             | |
       | |             | |
       v |             | |
  ______ ______        | |
 [___STARTED___]       | |
                       | |
       | ^             | |
       | |             | |
    run| |repeat       | |stop
       | |             | |
       v |             v |
  ____________________________
 [__________RUNNING___________]

========================================================================= *
EXPECTED SIGNAL EMISSIONS
========================================================================= *

start()  -> startedChanged
run()    -> runningChanged + runningStarted
stop()   -> runningChanged + startedChanged
repeat() -> runningChanged

Note: Excluding keepalive handling
      RUNNING->repeat() equals RUNNING->stop() + RUNNING->start()
      and IDLE->repeat() equals IDLE->start()

========================================================================= *
ACTIVITY AFTER PERIODICAL WAKEUPS
========================================================================= *

Expected use cases:
* anything that needs to wake up periodically to do some processing
* possible examples might be: ssu, rss, email, facebook, ...

IPHB            BGA                      APP  STARTED RUNNING
  |              |                        |
  |              |                        |        F   F
  |              |                        |
  |              | <---setInterval------- |
  |              | <---start------------- |
  |              |                        |
  |              | ----startedChanged---> |       >T
  | <---wait---- |                        |
  Z              |                        |
  | ---wakeup--> |                        |
  |              | ----runningChanged---> |           >T
  |              | ----runningStarted---> |           >T
  |              |                        Z
  |              | <---repeat------------ |
  |              | ----runningChanged---> |           >F
  | <---wait---- |                        |
  Z              |                        |
  | ---wakeup--> |                        |
  |              | ----runningChanged---> |           >T
  |              | ----runningStarted---> |           >T
  |              |                        Z
  |              | <---stop-------------- |
  |              | ----runningChanged---> |           >F
  |              | ----startedChanged---> |       >F
  |              |                        |

========================================================================= *
ACTIVITY AFTER ONESHOT WAKEUP
========================================================================= *

Expected use cases:
* Anything that needs to do something after delay that is long enough
  to allow inactivity to turn the display off (and thus suspend)
* possible examples might be: 1/2/3 minute timers in clock ui
  (AFAIK those do not use timed)

IPHB            BGA                      APP  STARTED RUNNING
  |              |                        |
  |              |                        |        F   F
  |              |                        |
  |              | <---setSingleShot----- |
  |              | <---setInterval------- |
  |              |                        |
  |              | <---start------------- |
  |              | ----startedChanged---> |       >T
  | <---wait---- |                        |
  Z              |                        |
  | ---wakeup--> |                        |
  |              | ----runningChanged---> |           >T
  |              | ----runningStarted---> |           >T
  |              |                        Z
  |              | <---stop-------------- |
  |              | ----runningChanged---> |           >F
  |              | ----startedChanged---> |       >F
  |              |                        |

========================================================================= *
ACTIVITY AFTER CHAINED ONESHOT WAKEUPS
========================================================================= *

Expected use cases:
* anything with pool of more or less irregular wakeups to drain
* possible examples might be: buteo, timed, cron,
  (conditional wakeups mw, if we ever implement something like that)

IPHB            BGA                      APP  STARTED RUNNING
  |              |                        |
  |              |                        |        F   F
  |              |                        |
  |              | <---setSingleShot----- |
  |              | <---setInterval------- |
  |              |                        |
  |              | <---start------------- |
  |              | ----startedChanged---> |       >T
  | <---wait---- |                        |
  Z              |                        |
  | ---wakeup--> |                        |
  |              | ----runningChanged---> |           >T
  |              | ----runningStarted---> |           >T
  |              |                        Z
  |              | <---repeat------------ |
  |              | ----runningChanged---> |           >F
  | <---wait---- |                        |
  Z              |                        |
  | ---wakeup--> |                        |
  |              | ----runningChanged---> |           >T
  |              | ----runningStarted---> |           >T
  |              |                        Z
  |              | <---stop-------------- |
  |              | ----runningChanged---> |           >F
  |              | ----startedChanged---> |       >F
  |              |                        |

========================================================================= *
ACTIVITY WITHOUT WAKEUP
========================================================================= *

Expected use cases:
* anything that starts from user activity and must block the
  device from going into suspend before it is finished (even though
  we would allow the display to be blanked)
* possible examples might be: backup/restore, "refresh now" actions

IPHB            BGA                      APP  STARTED RUNNING
  |              |                        |
  |              |                        |        F   F
  |              | <---run--------------- |
  |              |                        |
  |              | ----runningChanged---> |           >T
  |              | ----runningStarted---> |           >T
  |              |                        Z
  |              | <---stop-------------- |
  |              | ----runningChanged---> |           >F
  |              |                        |
