facilitate tracking of IndexedDB item store contents

1 files changed, 14 insertions, 0 deletions

diff --git a/common/broadcast.js b/common/broadcast.js
index bc18103..cc11a20 100644
--- a/common/broadcast.js
+++ b/common/broadcast.js
@@ -59,6 +59,20 @@ function out(sender_conn, channel_name, value)
     sender_conn.port.postMessage(["broadcast", channel_name, value]);
 }
 
+/*
+ * prepare()'d message will be broadcasted if the connection is closed or when
+ * flush() is called. All messages prepared by given sender will be discarded
+ * when discard() is called.
+ *
+ * Timeout will cause the prepared message to be broadcasted after given number
+ * of miliseconds unless discard() is called in the meantime. It is mostly
+ * useful as a fallback in case this connection end gets nuked (e.g. because
+ * browser window is closed) and onDisconnect event is not dispatched to
+ * background script's Port object. This is only an issue for browsers as old as
+ * IceCat 60: https://bugzilla.mozilla.org/show_bug.cgi?id=1392067
+ *
+ * Timeout won't be scheduled at all if its value is given as 0.
+ */
 function prepare(sender_conn, channel_name, value, timeout=5000)
 {
     sender_conn.port.postMessage(["prepare", channel_name, value, timeout]);