Additions to Activities to allow resource management

athena/activity/public/activity.h

Index: athena/activity/public/activity.h
diff --git a/athena/activity/public/activity.h b/athena/activity/public/activity.h
index 600182fd4f15ec017c5008f27fb914e13d262203..0ad4fd9d3bacdd4b97ec7b1f26d4820d080ed63e 100644
--- a/athena/activity/public/activity.h
+++ b/athena/activity/public/activity.h
@@ -13,12 +13,63 @@ namespace athena {
 
 class ActivityViewModel;
 
+// This class is a high level abstraction of an activity (which could be either
+// a web page or a V1/V2 app/extension). Through this class the activity can
+// be controlled (e.g. loaded / unloaded).
+// When an Activity gets created, it has the state "ACTIVITY_STATE_UNLOADED".
+// To load the activity the |ACTIVITY_LOAD| state transition needs to be called.
+// Destroying an Activity will call "ACTIVITY_UNLOAD" if required.
+// An invisible activity uses less resources then a visible one and progressing
+// through subsequent state transitions (HIDE -> DEEP_SLEEP_1 -> DEEP_SLEEP_2)
+// will reduce the resources even more.
+// An Activity which uses other media then the screen - like e.g. audio - can
+// remain |ACTIVITY_STATE_ACTIVE| not allowing to release any further resources.
 class ATHENA_EXPORT Activity {
  public:
+  // The state the activity is in.
+  enum ActivityState {
+    // The activity is not loaded/running.
+    ACTIVITY_STATE_UNLOADED,
+    // The activity is visible on a screen.
+    ACTIVITY_STATE_VISIBLE,
+    // The activity is not visible, but it is active e.g. by streaming audio.

[Jun Mukai, 2014/06/26 19:48:01]

Got confused by the comment a bit. So ACTIVE doesn't mean the active-ness in
ui/wm context (meaning topmost / keyboard event handling) but something
different? Can we use another term here? I don't have concrete alternatives
though...

[Mr4D (OOO till 08-26), 2014/06/26 20:25:39]

Sure!

Note: There are 2 "Active" levels: 1=Visible (means: activity is full on)
2=(Audio)Active (means that the activity is actively doing something and it
should kept in a running state (releasing gfx resources though)

So - what about ACTIVITY_STATE_BACKGROUND_ACTIVE?

+    ACTIVITY_STATE_ACTIVE,
+    // The activity is hidden but still active by playing audio.
+    ACTIVITY_STATE_HIDDEN,
+    // The activity has given up some resources which increases time to regain a
+    // visible state.
+    ACTIVITY_STATE_DEEP_SLEEP_1,

[Jun Mukai, 2014/06/26 19:48:01]

sleep_1 and sleep_2 doesn't sound good... :(

[Mr4D (OOO till 08-26), 2014/06/26 20:25:39]

Right. I was hoping to nail this down in this weeks EngReview meeting - but that
did not take place. For the time being I might simply remove "_1" and the entire
second state.

+    // The activity has given up all re-creatable resources and might take a
+    // considerable time to regain a visible state.
+    ACTIVITY_STATE_DEEP_SLEEP_2
+  };
+
+  // The state an activity should be in as requested by e.g. the resource
+  // management system.
+  enum ActivityStateTransition {
+    // (Re-)load the activity for the first time or after eviction. Note that
+    // a visibility change does not necessarily trigger a reload.
+    ACTIVITY_LOAD,
+    // The activity should surrender additional resources. This has only an
+    // effect when the activity is in a loaded state (Visible, Active, Hidden).
+    ACTIVITY_DEEP_SLEEP_1,
+    // The activity should surrender all re-creatable resources. This has only
+    // an effect when the activity is currently in ACTIVITY_DEEP_SLEEP_1.
+    ACTIVITY_DEEP_SLEEP_2,
+    // Unloads the activity and can be called in any state - but unloaded.
+    ACTIVITY_UNLOAD
+  };
+
   virtual ~Activity();
 
   // The Activity retains ownership of the returned view-model.
   virtual ActivityViewModel* GetActivityViewModel() = 0;
+
+  // Transition the activity into a new state.
+  void SetCurrentState(ActivityStateTransition state) = 0;
+
+  // Returns the current state of the activity.
+  ActivityState GetCurrentState() = 0;
 };
 
 }  // namespace athena