Merge pull request #2928 from waywardmonkeys/trace-extensions

Trace extensions

site/source/docs/api_reference/trace.h.rst

@@ -131,6 +131,14 @@ memory, you can annotate the address:
 
   emscripten_trace_annotate_address_type(model, "UI::Model");
 
+Additionally, some applications may want to associate the size
+of additional storage with an allocation. This can be done via
+:c:func:`emscripten_trace_associate_storage_size`:
+
+.. code-block:: c
+
+  emscripten_trace_associate_storage_size(mesh, mesh->GetTotalMemoryUsage());
+
 Overall Memory Usage
 --------------------
 
@@ -164,6 +172,49 @@ cause large amounts of memory activity, like loading a new
 model or game asset, is very useful when analyzing memory
 usage behavior patterns.
 
+Tasks
+-----
+
+Specific tasks can be recorded and analyzed. A task is typically
+a unit of work that is not repeating. It may be suspended or
+blocked due to having portions performed asynchronously.
+
+An example of a task is loading an asset which usually involves
+chains of callbacks.
+
+The application should keep track of task IDs (integers) and
+ensure that they are unique.
+
+The task ID need not be passed to every trace call involving
+tasks as most calls operate on the current task.
+
+Tasks can be started and stopped with:
+
+.. code-block:: c
+
+  emscripten_trace_task_start(taskID, name);
+  emscripten_trace_task_end();
+
+If a task is suspended / blocked, this can be noted via:
+
+.. code-block:: c
+
+  emscripten_trace_task_suspend("loading via HTTP");
+
+And when it is resumed:
+
+.. code-block:: c
+
+  emscripten_trace_task_resume(taskID, "parsing");
+
+It is common to need to associate additional data with the
+current task for use when examining task data later. An example
+of this would be the URL of an asset that was loaded:
+
+.. code-block:: c
+
+  emscripten_trace_task_associate_data("url", url);
+
 Reporting Errors
 ----------------
 
@@ -371,6 +422,26 @@ Functions
    stored there. This is used by the server to help breakdown
    what is in memory.
 
+.. c:function:: void emscripten_trace_associate_storage_size(const void *address, int32_t size)
+
+   :param address: Memory address which should be annotated.
+   :type address: void*
+   :param size: Size of the memory associated with this allocation.
+   :type type: int32_t
+   :rtype: void
+
+   Associate an amount of additional storage with this address. This
+   does not represent the size of the allocation itself, but rather
+   associated memory that should be taken into account when looking
+   at the size of this object.
+
+   This associated storage is application specific in nature.
+
+   An example is when an object contains a vector or string, you may
+   want to be aware of that when analyzing memory usage and this
+   provides a way to let the server be aware of that additional
+   storage.
+
 .. c:function:: void emscripten_trace_report_memory_layout(void)
 
    :rtype: void
@@ -401,15 +472,72 @@ Functions
 
    The current timestamp is associated with this data.
 
-   *This is not yet used on the server side.*
-
 .. c:function:: void emscripten_trace_exit_context(void)
 
    :rtype: void
 
    The current timestamp is associated with this data.
 
-   *This is not yet used on the server side.*
+.. c:function:: void emscripten_trace_task_start(int task_id, const char *name);
+
+   :param task_id: Task ID
+   :type task_id: int
+   :param name: Task name
+   :type name: const char*
+   :rtype: void
+
+   A task is initiated. The task ID should be unique over the lifetime of
+   the application. It should be managed / tracked by the application.
+
+   The current timestamp is associated with this data.
+
+.. c:function:: void emscripten_trace_task_associate_data(const char *key, const char *value);
+
+   :param key: Key
+   :type key: const char*
+   :param value: Value
+   :type value: const char*
+   :rtype: void
+
+   Associate a key / value pair with the current task.
+
+.. c:function:: void emscripten_trace_task_suspend(const char *explanation);
+
+   :param explanation: Why the task is suspending.
+   :type explanation: const char*
+   :rtype: void
+
+   The current task is suspended.
+
+   The explanation should indicate why the task is being suspended
+   so that this information can be made available when viewing the
+   task's history.
+
+   The current timestamp is associated with this data.
+
+.. c:function:: void emscripten_trace_task_resume(int task_id, const char *explanation);
+
+   :param task_id: Task ID
+   :type task_id: int
+   :param explanation: Why the task is being resumed.
+   :type explanation: const char*
+   :rtype: void
+
+   The task identified by ``task_id`` is resumed and made the current task.
+
+   The explanation should indicate what the task is being resumed to do
+   so that this information can be made available when viewing the task's
+   history.
+
+   The current timestamp is associated with this data.
+
+.. c:function:: void emscripten_trace_task_end(void);
+
+   :rtype: void
+
+   The current task is ended.
+
+   The current timestamp is associated with this data.
 
 .. c:function:: void emscripten_trace_close(void)
 

src/library_trace.js

@@ -16,6 +16,7 @@ var LibraryTracing = {
     EVENT_ALLOCATE: 'allocate',
     EVENT_ANNOTATE_TYPE: 'annotate-type',
     EVENT_APPLICATION_NAME: 'application-name',
+    EVENT_ASSOCIATE_STORAGE_SIZE: 'associate-storage-size',
     EVENT_ENTER_CONTEXT: 'enter-context',
     EVENT_EXIT_CONTEXT: 'exit-context',
     EVENT_FRAME_END: 'frame-end',
@@ -28,6 +29,11 @@ var LibraryTracing = {
     EVENT_REALLOCATE: 'reallocate',
     EVENT_REPORT_ERROR: 'report-error',
     EVENT_SESSION_NAME: 'session-name',
+    EVENT_TASK_ASSOCIATE_DATA: 'task-associate-data',
+    EVENT_TASK_END: 'task-end',
+    EVENT_TASK_RESUME: 'task-resume',
+    EVENT_TASK_START: 'task-start',
+    EVENT_TASK_SUSPEND: 'task-suspend',
     EVENT_USER_NAME: 'user-name',
 
     init: function() {
@@ -179,6 +185,13 @@ var LibraryTracing = {
     }
   },
 
+  emscripten_trace_associate_storage_size: function(address, size) {
+    if (EmscriptenTrace.enabled) {
+      EmscriptenTrace.post([EmscriptenTrace.EVENT_ANNOTATE_TYPE,
+                            address, size]);
+    }
+  },
+
   emscripten_trace_report_memory_layout: function() {
     if (EmscriptenTrace.enabled) {
       var memory_layout = {
@@ -243,6 +256,45 @@ var LibraryTracing = {
     }
   },
 
+  emscripten_trace_task_start: function(task_id, name) {
+    if (EmscriptenTrace.enabled) {
+      var now = EmscriptenTrace.now();
+      EmscriptenTrace.post([EmscriptenTrace.EVENT_TASK_START,
+                            now, task_id, Pointer_stringify(name)]);
+    }
+  },
+
+  emscripten_trace_task_associate_data: function(key, value) {
+    if (EmscriptenTrace.enabled) {
+      EmscriptenTrace.post([EmscriptenTrace.EVENT_TASK_ASSOCIATE_DATA,
+                            Pointer_stringify(key),
+                            Pointer_stringify(value)]);
+    }
+  },
+
+  emscripten_trace_task_suspend: function(explanation) {
+    if (EmscriptenTrace.enabled) {
+      var now = EmscriptenTrace.now();
+      EmscriptenTrace.post([EmscriptenTrace.EVENT_TASK_SUSPEND,
+                            now, Pointer_stringify(explanation)]);
+    }
+  },
+
+  emscripten_trace_task_resume: function(task_id, explanation) {
+    if (EmscriptenTrace.enabled) {
+      var now = EmscriptenTrace.now();
+      EmscriptenTrace.post([EmscriptenTrace.EVENT_TASK_RESUME,
+                            now, task_id, Pointer_stringify(explanation)]);
+    }
+  },
+
+  emscripten_trace_task_end: function() {
+    if (EmscriptenTrace.enabled) {
+      var now = EmscriptenTrace.now();
+      EmscriptenTrace.post([EmscriptenTrace.EVENT_TASK_END, now]);
+    }
+  },
+
   emscripten_trace_close: function() {
     EmscriptenTrace.configured = false;
     EmscriptenTrace.enabled = false;

system/include/emscripten/trace.h

@@ -34,6 +34,8 @@ void emscripten_trace_record_free(const void *address);
 
 void emscripten_trace_annotate_address_type(const void *address, const char *type);
 
+void emscripten_trace_associate_storage_size(const void *address, int32_t size);
+
 void emscripten_trace_report_memory_layout(void);
 
 void emscripten_trace_report_off_heap_data(void);
@@ -42,6 +44,16 @@ void emscripten_trace_enter_context(const char *name);
 
 void emscripten_trace_exit_context(void);
 
+void emscripten_trace_task_start(int task_id, const char *name);
+
+void emscripten_trace_task_associate_data(const char *key, const char *value);
+
+void emscripten_trace_task_suspend(const char *explanation);
+
+void emscripten_trace_task_resume(int task_id, const char *explanation);
+
+void emscripten_trace_task_end(void);
+
 void emscripten_trace_close(void);
 
 #else
@@ -62,6 +74,11 @@ void emscripten_trace_close(void);
 #define emscripten_trace_report_off_heap_data()
 #define emscripten_trace_enter_context(name)
 #define emscripten_trace_exit_context()
+#define emscripten_trace_task_start(task_id, taskname)
+#define emscripten_trace_task_associate_data(key, value);
+#define emscripten_trace_task_suspend(explanation);
+#define emscripten_trace_task_resume(task_id, explanation);
+#define emscripten_trace_task_end();
 #define emscripten_trace_close()
 
 #endif