Improving the process model extension API

chrome/common/extensions/api/experimental.processes.json

Index: chrome/common/extensions/api/experimental.processes.json
diff --git a/chrome/common/extensions/api/experimental.processes.json b/chrome/common/extensions/api/experimental.processes.json
index be7cf5269bfabe43025f80d03ecaa977ebf47633..054aba3cf6cb18c18ed0b01913fccfe82cf13daa 100644
--- a/chrome/common/extensions/api/experimental.processes.json
+++ b/chrome/common/extensions/api/experimental.processes.json
@@ -5,7 +5,6 @@
 [
   {
     "namespace": "experimental.processes",
-    "nodoc": true,
     "types": [
       {
         "id": "Process",
@@ -14,6 +13,10 @@
         "properties": {
           "id": {
             "type": "integer",
+            "description": "Unique ID of the process provided by Chrome." 
+          },
+          "osProcessId": {
+            "type": "integer",
             "description": "The ID of the process, as provided by the OS."
           },
           "type": {
@@ -21,27 +24,113 @@
             "enum": ["browser", "renderer", "extension", "notification", "plugin", "worker", "nacl", "utility", "gpu", "other"],
             "description": "The type of process."
           },
+          "profile": {
+            "type": "string",
+            "description": "The profile which the process is associated with."
+          },
+          "tabs": {

[Charlie Reis, 2012/05/04 20:41:30]

The API doc says this is optional, but we appear to be returning an empty list
for non-renderers instead.  Empty list sounds fine, so let's update the API doc.

[nasko, 2012/05/07 17:08:47]

Doc updated.

+            "type": "array",  "items": {"type": "integer", "minimum": 0},
+            "description": "Array of Tab IDs that have a page rendered by this process (for renderer processes only)."
+          },
           "cpu": {
             "type": "number",
-            "description": "The most recent measurement of the process's CPU usage, between 0 and 100%."
+            "optional": true,
+            "description": "The most recent measurement of the process CPU usage, between 0 and 100%."

[Charlie Reis, 2012/05/04 20:41:30]

I think we do want to include the clauses about when these are available (from
the API doc).  This file gets machine translated into the docs that users will
be referencing.

[nasko, 2012/05/07 17:08:47]

I've synced all the others with the clause from the API doc.

           },
           "network": {
             "type": "number",
-            "description": "The most recent measurement of the process's network usage, in bytes per second."
+            "optional": true,
+            "description": "The most recent measurement of the process network usage, in bytes per second."
           },
           "privateMemory": {
             "type": "number",
-            "description": "The most recent measurement of the process's private memory usage, in bytes."
+            "optional": true,
+            "description": "The most recent measurement of the process private memory usage, in bytes."
+          },
+          "memoryUsage": {

[Charlie Reis, 2012/05/04 20:41:30]

This is still here.  Please remove.

[nasko, 2012/05/07 17:08:47]

Done.

+            "$ref": "MemoryUsage",
+            "optional": true,
+            "description": "Object containing the most recent details about process memory usage, in bytes."
+          },
+          "jsMemoryAllocated": {
+            "type": "number",
+            "optional": true,
+            "description": "The most recent measurement of the process JavaScript allocated memory, in bytes."
+          },
+          "jsMemoryUsed": {
+            "type": "number",
+            "optional": true,
+            "description": "The most recent measurement of the process JavaScript memory used, in bytes."
+          },
+          "sqliteMemory": {
+            "type": "number",
+            "optional": true,
+            "description": "The most recent measurement of the process’s SQLite memory usage, in bytes."
+          },
+          "fps": {
+            "type": "number",
+            "optional": true,
+            "description": "The most recent measurement of the process frames per second."
+          },
+          "imageCache": {
+            "$ref": "Cache",
+            "optional": true,
+            "description": "The most recent information about the image cache for the process."
+          },
+          "scriptCache": {
+            "$ref": "Cache",
+            "optional": true,
+            "description": "The most recent information about the script cache for the process."
+          },
+          "cssCache": {
+            "$ref": "Cache",
+            "optional": true,
+            "description": "The most recent information about the CSS cache for the process."
+          }
+        }
+      },
+      {
+        "id": "Cache",
+        "type": "object",
+        "description": "The Cache object contains information about the size and utilization of a cache used by Chromium.",

[Charlie Reis, 2012/05/04 20:41:30]

We should be consistent about Chrome vs Chromium in this file.  (I'm guessing
Chrome, but please check the other API docs.)

[nasko, 2012/05/07 17:08:47]

Replaced by "the browser" to be agnostic to the naming of it. Tabs docs seem to
use that approach.

+        "properties": {
+          "size": {
+            "type": "number",
+            "description": "The size of the cache, in bytes."
           },
-          "sharedMemory": {
+          "liveSize": {
             "type": "number",
-            "description": "The most recent measurement of the process's shared memory usage, in bytes."
+            "description": "The part of the cache that is utilized, in bytes."
           }
         }
       }
     ],
     "functions": [
       {
+        "name": "terminate",
+        "type": "function",
+        "description": "Terminates the specified renderer process. Equivalent to visiting about:crash, but without changing the tab's URL.",
+        "parameters": [
+          {
+            "name": "processId",
+            "type": "integer",
+            "minimum": 0
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [
+              {
+                "name": "didTerminate",
+                "type": "boolean",
+                "description": "True if the process was successfully killed."
+              }
+            ]
+          }
+        ]
+      },
+      {
         "name": "getProcessIdForTab",
         "type": "function",
         "description": "Returns the ID of the renderer process for the specified tab.",
@@ -52,8 +141,8 @@
             "minimum": 0
           },
           {
-            "type": "function",
             "name": "callback",
+            "type": "function",
             "parameters": [
               {
                 "name": "processId",
@@ -63,6 +152,36 @@
             ]
           }
         ]
+      },
+      {
+        "name": "getProcessInfo",
+        "type": "function",
+        "description": "Retrieves the process information for each process ID specified.",
+        "parameters": [
+          {
+            "name": "processIds",
+            "choices": [
+              {"type": "integer", "minimum": 0},
+              {"type": "array", "items": {"type": "integer", "minimum": 0}}
+            ]
+          },
+          {
+            "name": "includeMemory",
+            "type": "boolean"

[Charlie Reis, 2012/05/04 20:41:30]

Please include descriptions of all the parameters for each function.

[nasko, 2012/05/07 17:08:47]

Done.

+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "parameters": [
+              {
+                "name": "processes",
+                "description": "",
+                "type": "object",
+                "additionalProperties": { "$ref": "Process" }
+              }
+            ]
+          }
+        ]
       }
     ],
     "events": [
@@ -77,6 +196,63 @@
             "additionalProperties": { "$ref": "Process" }
           }
         ]
+      },
+      {
+        "name": "onUpdatedWithMemory",
+        "type": "function",
+        "description": "Fired each time the Task Manager updates its process statistics, providing the dictionary of updated Process objects, indexed by process ID. Identical to onUpdate, with the addition of memory usage details included in each Process object. Note, collecting memory usage information incurs extra CPU usage and should only be listened for when needed.",
+        "parameters": [
+          {
+            "name": "processes",
+            "type": "object",
+            "additionalProperties": { "$ref": "Process" }
+          }
+        ]
+      },
+      {
+        "name": "onCreated",
+        "type": "function",
+        "description": "Fired each time a process is created, providing the corrseponding Process object.",
+        "parameters": [
+          {
+            "name": "processId",
+            "type": "integer"
+          },
+          {
+            "name": "process",
+            "$ref": "Process"
+          }
+        ]
+      },
+      {
+        "name": "onUnresponsive",
+        "type": "function",
+        "description": "Fired each time a process becomes unresponsive, providing the corrseponding Process object.",
+        "parameters": [
+          {
+            "name": "process",
+            "$ref": "Process"
+          }
+        ]
+      },
+      {
+        "name": "onExited",
+        "type": "function",
+        "description": "Fired each time a process is terminated, providing the type of exit.",
+        "parameters": [
+          {
+            "name": "processId",
+            "type": "integer"
+          },
+          {
+            "name": "exitType",
+            "type": "integer"
+          },
+          {
+            "name": "exitCode",
+            "type": "integer"
+          }
+        ]
       }
     ]
   }