Additions to Activities to allow resource management

athena/activity/public/activity.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef ATHENA_ACTIVITY_PUBLIC_ACTIVITY_H_
 #define ATHENA_ACTIVITY_PUBLIC_ACTIVITY_H_
 
 #include <string>
 
 #include "athena/athena_export.h"
 
 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.
+    ACTIVITY_STATE_BACKGROUND_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,
+    // 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
+  };

[oshima, 2014/07/11 18:02:59]

As per discussion, I'd recommend to start with hour states,

ACTIVITY_UNLOADED,
ACTIVITY_PERSISTENT,
ACTIVITY_BACKGROUND_LOW_PRIORITY,
ACTIVITY_NORMAL

and use the state as a transition command. We can add more states as we make
progress.

[Mr4D (OOO till 08-26), 2014/07/11 22:38:08]

Changed as discussed

+
+  // 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.
+  virtual void SetCurrentState(ActivityStateTransition state) = 0;
+
+  // Returns the current state of the activity.
+  virtual ActivityState GetCurrentState() = 0;
 };
 
 }  // namespace athena
 
 #endif  // ATHENA_ACTIVITY_PUBLIC_ACTIVITY_H_